WebSockets

hookstream provides three WebSocket endpoints for real-time communication. All connections use Cloudflare Durable Objects with the Hibernatable WebSocket API — efficient, stateful connections that survive idle periods without cost.

WebSocket upgrades cannot use custom request headers in browsers, so API keys are passed via the token query parameter instead of X-API-Key. Browser clients signed in to the dashboard use session cookies automatically.

Dashboard Stream

GET /v1/ws

Upgrade to authenticated WebSocket for real-time organization-wide event streaming. After connecting, you receive real-time events for your organization across all sources and destinations. Messages are JSON with a channel field for filtering (e.g., events, deliveries, issues).

Authentication: API key via token query param, or session cookie.

Query Parameters

js
// Uses session cookie automatically
const ws = new WebSocket("wss://hookstream.io/v1/ws");

ws.addEventListener("message", (event) => {
  const msg = JSON.parse(event.data);
  console.log(msg.channel, msg.data);
});

js
import WebSocket from "ws";

const ws = new WebSocket(
  `wss://hookstream.io/v1/ws?token=${process.env.HOOKSTREAM_API_KEY}`
);

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  console.log(msg.channel, msg.data);
});

bash
hookstream listen

json
{
  "type": "event",
  "channel": "events",
  "data": {
    "id": "evt_d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9",
    "source_id": "src_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "method": "POST",
    "status": "delivered",
    "received_at": "2026-03-01T14:30:00Z"
  }
}

Test Session Stream

GET /v1/ws/test/:source_id

Upgrade to unauthenticated WebSocket for a test session's real-time event feed. Used by the browser-based test inspector.

Authentication: None. Validates the source is an ephemeral test session.

js
const sessionId = "a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8";
const ws = new WebSocket(`wss://hookstream.io/v1/ws/test/${sessionId}`);

ws.addEventListener("message", (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === "event") {
    console.log("New webhook:", msg.data);
  }
});

json
{
  "type": "event",
  "channel": "test",
  "data": {
    "id": "evt_001",
    "method": "POST",
    "body": { "test": true },
    "received_at": "2026-03-01T12:05:00Z"
  }
}

Inbound WebSocket Source

GET /v1/ws/source/:source_id

Upgrade to authenticated WebSocket for inbound event ingestion. Instead of receiving HTTP webhooks, you can send events over a persistent WebSocket connection. Each message sent on this connection is ingested as an event and routed through the normal delivery pipeline. Useful for high-throughput or bidirectional scenarios.

Authentication: API key via token query param.

Query Parameters

js
import WebSocket from "ws";

const ws = new WebSocket(
  `wss://hookstream.io/v1/ws/source/src_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6?token=${process.env.HOOKSTREAM_API_KEY}`
);

ws.on("open", () => {
  ws.send(JSON.stringify({
    type: "order.created",
    data: { id: "ord_123", amount: 4999 },
  }));
});

ws.on("message", (raw) => {
  const ack = JSON.parse(raw.toString());
  console.log("Event ID:", ack.event_id);
});

json
{
  "type": "order.created",
  "data": { "id": "ord_123", "amount": 4999 }
}

json
{
  "type": "ack",
  "event_id": "evt_d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9"
}

Message format

All WebSocket messages are JSON objects with a type field indicating the message kind.

Server → client:

Client → server:

Related