WebSocket Streaming

WebSocket is a second way to receive Event Streaming data, alongside webhooks. It supports all the same chains and rules as webhooks — the difference is entirely in how the connection is established.

When to use websocket

See the comparison on Webhook Streaming documentation.

Target lifecycle

A WebSocket target goes through the same three states as a webhook target: active → connected → failed.

• On connect: when a WebSocket connection is established, the target is updated to connected.
• On disconnect: the target is marked failed only once all connections for that target have disconnected — multiple simultaneous WebSocket connections are allowed per target, and the target stays connected as long as at least one remains open.
• On service startup: targets with no active connection recorded are marked failed.

Liveness is tracked internally using a short-TTL key that's continuously refreshed while a connection is active, rather than a client-facing heartbeat message.

Archiving follows the same logic as webhook targets, based on target state and last-updated time.

Connecting

Create a WebSocket target the same way as a webhook target, using POST /targets, with "type": "websocket" instead of "webhook":

{
  "name": "my-websocket-target",
  "type": "websocket",
  "max_buffer_count": 2000,
  "settings": { "mode": "noack" }
}

The response's id is the target ID used to open the connection:

wss://svc.blockdaemon.com/streaming/v2/targets/{target_id}/websocket

Authenticate at connection time with a standard Authorization: Bearer <API_KEY> header on the WebSocket handshake request, the same API key used for the REST API. There's no separate handshake message or query-param authentication step.

Once connected, each event arrives as a single JSON text frame, one message per event, using the same envelope and templates (ALL_DATA, UNIFIED_V1, UNIFIED_V1_RAW) as webhook delivery. Rules and variables are created the same way for a WebSocket target as for a webhook target.

max_buffer_count has a minimum of 100; values below that are rejected.

Rules only match activity from the moment they're active. Connect and confirm the rules are live before triggering the activity being watched for; rules don't scan history retroactively.

No custom application-level heartbeat message is sent. The connection does use standard WebSocket protocol ping frames (per RFC 6455) for keepalive. A compliant WebSocket client handles these automatically at the protocol level without any application code needed.

Security

The WebSocket connection is secured with SSL. Authentication uses the same API key as the REST API, passed as a Bearer token on the connection request.