Webhooks

Webhooks notify your server when call events happen. You register an endpoint, Wave POSTs signed JSON to it, and retries on failure.

Register an endpoint

Webhook endpoints are managed in the Wave dashboard under Webhooks: add a URL, choose the events, and copy the signing secret (shown once). The URL must be a public https URL. Wave refuses a URL that points to a loopback, private, link-local or other internal address (400 WEBHOOK_URL_INVALID). Wave checks the address again before each delivery, and does not follow redirects.

One environment per endpoint

Each endpoint belongs to one environment: sandbox or production. It receives only the events of its environment, so test events never reach your live endpoint. In a production project, the dashboard shows the endpoints of the selected Environment view, and a new endpoint takes that view’s environment.

You can add the same URL once in each environment; each copy has its own signing secret.
The limit of 5 endpoints counts per environment.
A sandbox project cannot add a production endpoint. Add it on the Go-Live form instead: it stays inactive until Wave approves your request, and the form shows its signing secret once. If Wave rejects the request, the endpoint is removed.

Events

You can subscribe to any event below (max 5 endpoints per project). The How it is sent column tells you what an event needs before it reaches you:

Sent directly by the API — the API sends the event as soon as the action happens.
Sent through the event stream (enabled per environment) — the event comes from the voice engine or the messaging provider through Wave’s event stream. Where the event stream is not enabled, these events are not sent.
Not sent yet — you can subscribe now, but nothing sends the event yet.

Event	When	How it is sent
`call.initiated`	A call or callback starts	Sent directly by the API
`call.answered`	The call is answered	Sent through the event stream (enabled per environment)
`call.ended`	The call ends after it was answered	Sent through the event stream (enabled per environment)
`call.missed`	Nobody answered the call	Sent through the event stream (enabled per environment)
`call.timeout`	The call waited in the voice engine’s queue longer than the maximum wait (10 minutes) and was removed before dialling: the phone never rang and will not ring	Sent through the event stream (enabled per environment); in the sandbox, sent directly by the API (see below)
`call.cancelled`	You cancelled a callback (`DELETE /v1/callbacks/{id}`), or hung up a call that was still in the voice engine’s queue (`POST /v1/calls/{id}/hangup`): it is never dialled	Sent directly by the API for a callback cancel; through the event stream for a hang-up of a queued call
`call.failed`	The call could not be placed or connected	Sent through the event stream (enabled per environment)
`call.transferred`	A call transfer finished: one event per transfer, with `transfer_id`, `target` and `outcome`	Sent through the event stream (enabled per environment)
`call.held`	A call was put on hold	Not sent yet
`call.resumed`	A held call was resumed	Not sent yet
`call.input`	The caller pressed a key in a call flow menu (`data` has `digits` and, for the authentication menu, `authenticated`)	Sent directly by the API
`voice_auth.completed`	A voice authentication challenge reached its final state	Sent directly by the API
`verify.completed`	A verification reached its final state	Sent directly by the API
`voicemail.received`	A voicemail was recorded	Sent directly by the API
`message.received`	A message came in	Sent through the event stream (enabled per environment)
`message.delivered`	A message you sent was delivered	Sent through the event stream (enabled per environment)
`message.read`	A message you sent was read	Sent through the event stream (enabled per environment)
`message.failed`	A message you sent could not be delivered	Sent through the event stream (enabled per environment)
`conference.created`	A conference room started (first member joined)	Sent through the event stream (enabled per environment)
`conference.member_joined`	A call joined a conference room	Sent through the event stream (enabled per environment)
`conference.member_left`	A call left a conference room	Sent through the event stream (enabled per environment)
`conference.ended`	A conference room ended	Sent through the event stream (enabled per environment)
`campaign.recipient_completed`	A campaign recipient got its final outcome (no phone number in `data`)	Sent through the event stream (enabled per environment)
`campaign.completed`	A campaign finished or was stopped	Sent through the event stream (enabled per environment)

Sandbox keys. A sandbox callback to +966500000014 sends a simulated call.initiated → call.answered → call.ended sequence; one to +966500000015 sends call.initiated → call.missed; one to +966500000016 sends call.initiated → call.timeout. These are sent directly by the API, with "simulated": true in data.

Payload

Each delivery is a JSON body with the event type, the environment and a data object. The X-Wave-Event-Id header carries a unique id for idempotency.

{
  "event": "call.initiated",
  "environment": "production",
  "data": {
    "call_id": "call_abc123",
    "status": "initiated",
    "direction": "outbound",
    "from": "+96651XXXXXXX",
    "customer_number_masked": "+96650••••17",
    "queue_id": null,
    "provider_call_id": "…",
    "started_at": "2026-06-17T10:00:00.000Z",
    "metadata": {}
  }
}

environment sits next to event, outside data. It is "sandbox" or "production". Wave takes it from the call: a call that a sandbox key placed is "sandbox", and inbound calls are "production". The voice_auth.completed verdict webhook takes it from the key of the challenge. Every event carries the environment of its call, including the Verify, callback, voicemail, conference, IVR and transfer events.

Verifying the signature

Every delivery is signed. The X-Wave-Signature header is sha256=<hex> — an HMAC-SHA256 of the raw request body using your endpoint’s signing secret (whsec_…). Verify it with a constant-time compare before trusting the payload:

import crypto from "node:crypto";

function verifyWaveSignature(rawBody, header, secret) {
  if (!header?.startsWith("sha256=")) return false;
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

Compute the HMAC over the raw body bytes, before any JSON parse/re-serialize — re-stringifying can change the bytes and break the check.

Retries & dead-letter

Each attempt has a 10-second timeout. Failed deliveries retry up to 5 attempts on a backoff ladder, then dead-letter:

Attempt	Sent
1	immediately
2	+30s
3	+5m
4	+30m
5	+2h

Exhausted deliveries are dead-lettered (retained 72h) and appear in the dashboard’s delivery logs, marked Dead-lettered.

Get Started

Voice

Web Callback

WhatsApp

Reference

Register an endpoint

One environment per endpoint

Events

Payload

Verifying the signature

Retries & dead-letter

​Register an endpoint

​One environment per endpoint

​Events

​Payload

​Verifying the signature

​Retries & dead-letter

Register an endpoint

One environment per endpoint

Events

Payload

Verifying the signature

Retries & dead-letter