Get started
Webhooks overview
What webhooks are sent, in what order, and what your endpoint has to do.
A webhook is an HTTP POST from the platform to a URL of yours when something changes. The main one is the call webhook: the execution, sent on every status change of a call.
Setting it up
Set a webhook URL on the agent. Each agent can also have:
- headers sent with every delivery (stored encrypted, shown masked), for example a shared secret your endpoint checks;
- a status filter, if you only want some statuses, for example only
completed.
The details, with request examples, are in Webhooks in depth.
What you receive
The body is the execution as GET /executions/{execution_id} returns it at that moment: status, numbers, timings, and once the call has ended the transcript, cost, extracted data and recording URL.
A typical outbound call produces deliveries for queued, then the dialling and in-call statuses, then a final one such as completed, no-answer, busy or failed.
Delivery guarantees
| Property | Behaviour |
|---|---|
| Order | Deliveries for one call are sent in order. A later status is not sent before an earlier one has been delivered or given up on. |
| Retries | A delivery that fails (a non-2xx answer, a timeout, a connection error) is retried with backoff. |
| At least once | A delivery can arrive twice, for example if your endpoint answered slowly. Make your handler idempotent: key on the execution id and status. |
| Dead letters | A delivery that used up its attempts is kept in a dead-letter list, from which it can be sent again. |
What your endpoint should do
- Answer 2xx quickly, then do the work. A slow answer counts as a failure.
- Check the secret header you configured.
- Ignore a status you have already processed for that execution.
- Treat only a final status as the result of the call.
URLs that are refused
Webhook URLs may not point at private or loopback addresses. This protects the network the platform runs in. A development deployment can lift the restriction with ALLOW_PRIVATE_URLS; a production one should not.
Tools for debugging
| Need | Use |
|---|---|
| Send a sample delivery to your URL | POST /v2/agent/{agent_id}/webhook:test |
| See the deliveries of one call | GET /executions/{execution_id}/webhooks |
| Send a call's webhook again | POST /executions/{execution_id}/webhook:resend |
| List deliveries that ran out of attempts | GET /webhooks/dead |
Other webhooks
- Workflow webhooks report workflow executions. They are retried, but have no dead-letter view yet.
- Pre-call webhooks are requests the platform makes to you before dialling or before a tool runs, to fetch variables. Per-tool pre-call webhooks are not fired by the voice engine on live calls yet. See Function tools.
- Provider callbacks (payments, message delivery reports) are sent by third parties to the platform, not to you.
Limitation: Deliveries are not signed by the platform. Use a secret header and HTTPS to authenticate them.