Webhooks overview

The gateway sends events to your registered webhook URL. Unlike the request/response endpoints, webhooks are how you observe everything that happens on a call asynchronously.

Event envelope

Every webhook shares a common envelope:

{
  "event": "dtmf",
  "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "sequence": 7,
  "data": { }
}

Field	Type	Description
event	string	Event type, e.g. dtmf, call.hangup.
session_uuid	string	Session the event belongs to.
sequence	integer	Monotonic per-session counter.
data	object	Event-specific payload.

Command correlation

Completion events for asynchronous commands include a command_uid in their data object. This lets you reliably match a webhook to the command that triggered it — essential when commands overlap (for example, starting a new playback before the previous one finishes).

Ordering with sequence

• Starts at 1 — the first event for a session has sequence = 1.
• Monotonically increasing — each event increments the counter.

Use it to detect missing events (gaps) and to reorder out-of-order deliveries on the client.

Caution

If sequence is 0, the session was not found — for example, an event published after the session already ended.

Delivery guarantees

Webhooks are delivered with retry and dead-letter handling via Redis Streams. A failed delivery is retried with backoff; exhausted deliveries land in a dead-letter queue rather than being dropped silently.