Receive events

Whenever something happens on one of your sessions — a message arrives, a delivery receipt comes back, someone votes on a poll, a session changes status — the gateway produces an event. You read those events in one of two ways:

Both carry the same event envelope (the JSON wrapper described below), so the data you receive is identical whichever you pick.

The event envelope

Every event is one JSON object with the same outer fields:

{
  "schema": "v1",
  "id": "evt_01J9...",
  "event": "message",
  "session": "sess_01J8...",
  "organization": "org_abc",
  "timestamp": 1719400000000,
  "payload": { }
}

For every field of every payload type, with concrete examples, see Event shape.

Stream the events via WebSocket

The gateway delivers events over a WebSocket connection. The connection uses a two-step handshake: first you mint a single-use ticket, then you connect with that ticket.

Step 1: Mint a ticket

Send a POST request to /api/v1/realtime/ticket with your Bearer token. The request body is optional JSON:

curl -X POST https://your-gateway/api/v1/realtime/ticket \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "organization",
    "events": ["*"],
    "since": ""
  }'

The request body fields are all optional:

The response is JSON:

{
  "ticket": "rt_...",
  "expiresInSeconds": 30,
  "url": "wss://your-gateway/api/v1/realtime?ticket=rt_..."
}

The ticket is single-use and expires in about 30 seconds. Mint one ticket per connection, immediately before connecting. The ticket (not your bearer token) authorizes the WebSocket.

Step 2: Open the WebSocket

Connect to the URL returned in the ticket response (or build it: take your gateway base URL, swap http:// for ws:// and https:// for wss://, then append /api/v1/realtime?ticket=rt_...).

Over the socket the server sends discrete JSON text frames — one JSON object per frame:

• First frame: {"event":"connected","heartbeatSeconds":20,"timestamp":<epoch-ms>} — the connection is ready.
• Heartbeat: {"event":"ping","timestamp":<epoch-ms>} — sent about every 20 seconds. If pings stop, the connection is dead; reconnect.
• Error: {"event":"error","error":"<error message>"} — something went wrong.
• Data frame: The full event envelope (schema, id, event, session, organization, timestamp, payload).

Reconnect after a drop

To resume after a disconnect and get the events you missed, mint a new ticket with since set to the id of the last event you processed. The server replays everything after that id from its durable log (up to 1000 events), then resumes tailing live events. Replayed events are identical to live ones, so you must deduplicate on the event id.

Use webhooks instead

Register a webhook and the gateway delivers each matching event to your URL as a JSON POST. You create and manage webhooks through the gateway API (create a webhook); the dashboard shows the same config read-only.

A webhook is configured with:

Delivery headers

Every POST carries these headers:

Before you trust a delivery

• Check the signature. When the webhook has a secret, compute the HMAC-SHA512 of the exact raw request body using your secret, encode it as lowercase hex, and compare it to X-Webhook-Hmac. If they differ, reject the request. (HMAC is a keyed hash: only someone holding the secret can produce a matching value, so a match proves the body came from the gateway and was not altered.)
• Drop duplicates. A retried delivery repeats the same event id (X-Webhook-Request-Id). Keep track of ids you have already handled and skip repeats.

The gateway retries a failed delivery with growing gaps between attempts. Once a delivery is accepted (a 2xx response) it stops; once it runs out of retry attempts it is marked dead and not tried again.

Event catalog

Every event type the gateway emits. Set events to ["*"] (the default) to receive all of them, or list just the ones you want.