WebSocket Streaming

Developer

Receive filing alerts in real time over a persistent WebSocket connection. No polling required — filings are pushed to your client the instant they're processed.

Connection

Endpointwss://ws.8kintel.com
AuthPass your API key or Cognito JWT as a query parameter
Connect with auth token
const ws = new WebSocket("wss://ws.8kintel.com?token=YOUR_API_KEY");

ws.onopen = () => {
  console.log("Connected to 8K Intel WebSocket");
};

ws.onmessage = (event) => {
  const alert = JSON.parse(event.data);
  console.log(`[${alert.ticker}] ${alert.headline}`);
};

ws.onclose = () => {
  console.log("Disconnected — reconnecting in 5s...");
  setTimeout(connect, 5000);
};
Python (websockets)
import asyncio
import websockets
import json

async def listen():
    uri = "wss://ws.8kintel.com?token=YOUR_API_KEY"
    async with websockets.connect(uri) as ws:
        async for message in ws:
            alert = json.loads(message)
            print(f"[{alert['ticker']}] {alert['headline']}")

asyncio.run(listen())

Message Format

All messages are JSON objects with a type field. Currently the only message type is filing_alert.

filing_alert payload
{
  "type": "filing_alert",
  "filing_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "ticker": "AAPL",
  "sentiment": "bullish",
  "headline": "Q1 2026 revenue beats estimates by 8%, services hit all-time high",
  "title": "AAPL — Earnings",
  "body": "Revenue $124.3B vs $115.2B est. Services segment hits all-time high."
}
FieldTypeDescription
typestringAlways "filing_alert"
filing_idstringUUID — use to fetch full detail via REST API
tickerstringStock ticker symbol
sentimentstringbullish, bearish, or neutral
headlinestringAI-generated one-line summary
titlestringPush notification title (TICKER — Category)
bodystringPush notification body text

Connection Lifecycle

Connection

Connections are authenticated on connect via the token query parameter. Invalid or expired tokens receive a 4401 close code.

Keep-Alive

The server sends periodic ping frames. Connections idle for more than 10 minutes without a pong response are terminated.

Reconnection

Implement exponential backoff on disconnect. We recommend starting at 1 second and capping at 30 seconds. The connection store has a 24-hour TTL — reconnect before then.

Limits

Developer plans: 1 concurrent connection. Pro plans: up to 5 concurrent connections. Exceeding the limit closes the oldest connection.

Best Practices

  • •Use the filing_id to fetch full detail via GET /api/v1/filings/{id} — the WebSocket payload is a lightweight alert, not the full filing.
  • •Implement automatic reconnection with backoff. Network interruptions are normal.
  • •Buffer messages during reconnection and deduplicate by filing_id when you reconnect.
  • •For high-reliability use cases, combine WebSocket with webhooks as a fallback delivery channel.