Call webhooks

Events for calls on your numbers, both regular phone (PSTN) and WhatsApp, from ring to hangup. Delivery, retries, idempotency, and signature verification work the same for every event and are covered in the webhooks overview.

Events

Which events fire, in what order

Every call terminates with exactly one of call.ended or call.failed. Whether a call.received precedes it depends on the direction and channel:

Two details worth wiring into your handler:

• call.received fires at ring time, before anyone answers. A call nobody picks up still emits it, followed by call.ended with endReason: "no_answer".
• Unanswered is not failed. No-answer, busy, and rejected calls all terminate with call.ended (branch on endReason); call.failed is reserved for hard errors before or during bridging.

call.permission_request is independent of any single call: it fires when a WhatsApp user responds to a call-permission request, typically before your first business-initiated call to them.

---

call.received

Fired when a call is set up on one of your numbers: an inbound call, regular phone (PSTN) or WhatsApp, reaching the number and being routed to its configured destination (an AI voice agent, SIP endpoint, or phone number) — or an outbound WhatsApp call placed via the API, in which case direction is "outbound". The payload carries the Zernio call id, caller and business numbers, the destination snapshot (forwardTo), and contactId/conversationId links into the inbox so you can message the caller, during the call or after, with the regular send APIs. Subscribe with Create webhook settings or Update webhook settings.

---

call.ended

Fired when a call (phone/PSTN or WhatsApp) ends. Carries durationSeconds, the endReason (hangup, no_answer, rejected, error), and a cost breakdown under call.billing. The recording is not in this payload: it finishes processing a few seconds after hangup and lands on the call record — fetch it with GET /v1/calls/{id}/recording using the call.id from this event. The classic automation here is a missed-call follow-up: on endReason: "no_answer", text the caller back over the linked conversationId. Subscribe with Create webhook settings or Update webhook settings.

---

call.failed

Fired when a call (phone/PSTN or WhatsApp) fails with a hard error before or during bridging (for example, the destination rejected the SIP INVITE). Carries the platform error code and message. Subscribe with Create webhook settings or Update webhook settings.

---

call.permission_request

Fired when a WhatsApp user responds to your call-permission request (business-initiated calls require one). Carries the user's number, their response (accept or reject), whether it is permanent, and the expiry when it is not. Subscribe with Create webhook settings or Update webhook settings.