WebSocket Streaming

The Firehose streaming API is also available over WebSocket. Everything described in the HTTP Streaming guide — parameters, event format, keep-alive, rate limiting, and error codes — applies identically. This page covers the differences.

Endpoint

Connect using the WebSocket protocol on the same path:

wss://partners.ciscospaces.io/api/partners/v1/firehose/events

Regional endpoints:

Region	WebSocket URL
Rest of the World	`wss://partners.ciscospaces.io/api/partners/v1/firehose/events`
Europe	`wss://partners.ciscospaces.eu/api/partners/v1/firehose/events`
Singapore	`wss://partners.ciscospaces.sg/api/partners/v1/firehose/events`

Authentication

Pass the X-API-KEY header during the WebSocket handshake. The API key must resolve to an activation with the WebSocket endpoint type enabled.

Parameters

Parameters are passed as query string, same as HTTP:

wss://partners.ciscospaces.io/api/partners/v1/firehose/events?minPartition=1&maxPartition=6&fromTimestamp=1714989900000

See HTTP Streaming — Parameters for the full parameter reference.

Message Format

Each WebSocket text message contains one JSON event terminated by \n — the same NDJSON format as HTTP streaming. No additional framing is needed since WebSocket provides its own message boundaries.

The event record structure, field naming, and payload format are identical to HTTP. See HTTP Streaming — Event Record Structure and Sample Events for a complete reference.

Error Handling

WebSocket connections return the same HTTP status codes during the handshake:

Status	Cause
`401`	API key missing, invalid, or blocked
`403`	WebSocket endpoint type not enabled for activation
`400`	Invalid `replicaId` for cloud activation
`429`	Rate limit exceeded
`500`	Internal server error

When to Use WebSocket

Backend services deployed behind proxies or load balancers that buffer chunked HTTP responses
Application stacks with mature WebSocket client libraries (e.g., Java, Python, Node.js, Go)
Environments where maintaining a long-lived HTTP connection is operationally difficult

For most backend integrations, HTTP streaming is the simplest starting point. For high-throughput binary needs, consider gRPC.

Client Examples

Python

import websocket, json

def on_message(ws, message):
    event = json.loads(message)
    if event.get('eventType') == 'KEEP_ALIVE':
        return
    print(f"{event['eventType']}: {event['recordUid']}")

def on_error(ws, error):
    print(f"WebSocket error: {error}")

def on_close(ws, close_status_code, close_msg):
    print("WebSocket closed")

ws = websocket.WebSocketApp(
    'wss://partners.ciscospaces.io/api/partners/v1/firehose/events',
    header={'X-API-KEY': '<api-key>'},
    on_message=on_message,
    on_error=on_error,
    on_close=on_close
)
ws.run_forever()

Node.js

const WebSocket = require('ws');

const ws = new WebSocket(
  'wss://partners.ciscospaces.io/api/partners/v1/firehose/events',
  { headers: { 'X-API-KEY': '<api-key>' } }
);

ws.on('message', (data) => {
  const event = JSON.parse(data);
  if (event.eventType === 'KEEP_ALIVE') return;
  console.log(`${event.eventType}: ${event.recordUid}`);
});

ws.on('error', (err) => console.error('WebSocket error:', err));
ws.on('close', () => console.log('WebSocket closed'));