Get outcomes
Webhooks
Signed events pushed to your URL instead of polling. Delivery is a preview: build against the contract, poll for now.
Once delivery is on, we POST a signed JSON event to your URL as a lead and its calls move through their lifecycle. This page is the short version. The webhooks reference holds the full event catalog, every payload and the signature code.
There are two audiences. Partner subscriptions (POST /v1/webhooks) can receive all ten events, with the richer payloads. Agency integrations that set webhook_url on POST /calls get the call.* events except call.recording.ready, with leaner payloads.
Subscribing as a partner. The default events are lead.accepted, call.completed, call.transferred, call.analysis.completed, call.recording.ready and callback.scheduled. call.started, call.answered, call.failed and webhook.test are allowed but opt-in: list them in events to receive them.
Events
| Event | When | Audience |
|---|---|---|
lead.accepted | We enrolled the lead | Partner only |
call.started | The outbound dial was placed | Both |
call.answered | The lead picked up and the AI conversation began | Both |
call.completed | An attempt ended. Provisional | Both |
call.transferred | A warm transfer to a licensed agent has a result | Both |
call.failed | An accepted call could not complete | Both |
call.analysis.completed | The post-call summary is ready. Media may still be pending | Both |
call.recording.ready | The recording and transcript are fetchable | Partner only |
callback.scheduled | The lead asked to be called back | Partner only |
webhook.test | You asked us to send a test | Partner only |
Which event is final. call.recording.ready is final for partner subscriptions: write the disposition and artifacts to your system on it. Agency webhook_url callbacks never receive call.recording.ready, so call.analysis.completed is the last event for agency callbacks.
Leaner agency payloads. Agency callbacks carry no external_id and no media_pending, and a transfer carries transfer.to_agent in place of transfer.to_number and human_talk_seconds.
Choosing events on a call. webhook_events defaults to call.started, call.completed, call.failed and call.transferred. call.analysis.completed and call.answered are opt-in: add them to receive them. The disposition on call.completed is one of qualified_transfer, transferred, declined, no_answer, voicemail, callback_scheduled or connected_other.
Verify a delivery
We sign every delivery with the Standard Webhooks scheme, so you can verify it with an off-the-shelf library instead of hand-rolling HMAC. Each request carries three headers.
webhook-idstringOptionalThe event id, stable across retries. Dedupe on it: delivery is at least once.
webhook-timestampstringOptionalUnix seconds when we sent it. Reject a delivery more than 300 seconds off your clock, which stops replays. The libraries enforce this.
webhook-signaturestringOptionalOne or more space-separated v1,<base64 signature> entries. Several appear while a secret is being rotated, and any one match passes.
The signing secret starts with whsec_ and is shown once, when you enable webhooks. Keep it server-side. Verify against the raw request body, before any JSON parsing.
# pip install standardwebhooks
import os
from standardwebhooks.webhooks import Webhook
wh = Webhook(os.environ["ENTROVOX_WEBHOOK_SECRET"]) # whsec_…
def handle(raw_body: bytes, headers: dict):
# Raises WebhookVerificationError on a bad signature or a stale timestamp.
event = wh.verify(raw_body, headers)
return event// npm install standardwebhooks
import { Webhook } from "standardwebhooks";
const wh = new Webhook(process.env.ENTROVOX_WEBHOOK_SECRET); // whsec_…
export function handle(rawBody, headers) {
// Throws on a bad signature or a stale timestamp.
return wh.verify(rawBody, headers);
}To verify by hand: the HMAC-SHA256 key is the base64-decoded part of your secret after whsec_. Sign {webhook-id}.{webhook-timestamp}.{raw body bytes} exactly, base64-encode the digest and compare it in constant time against each v1, entry.
Delivery semantics
- At least once. You may receive duplicates. Dedupe on
webhook-id. - No ordering guarantee. Under retries
call.completedcan arrive beforecall.answered. Reconcile against the call's own state, not arrival order. - Respond fast. Return
2xxwithin about five seconds and process asynchronously. A non-2xxor a timeout triggers retries with exponential backoff, about five attempts over a few hours.
Events and payloads
Every delivery is a POST with this body:
{
"id": "evt_01J8…",
"type": "call.completed",
"created_at": "2026-07-04T19:30:00Z",
"api_version": "2026-09-10",
"data": {}
}id is unique per event, so dedupe on it. api_version is date-versioned so payloads can evolve safely. What data holds, per event, for a partner subscription:
type | data | Final? |
|---|---|---|
lead.accepted | lead, external_id | n/a |
webhook.test | ok: true | Ignore |
call.started, call.answered, call.failed | call, external_id | No |
call.completed | call, external_id, analysis_pending, media_pending | No |
call.transferred | call, external_id, transfer with status, to_number, initiated_at, connected_at, human_talk_seconds | Transfer result |
call.analysis.completed | call_id, external_id, analysis, links, media_pending | No, if media_pending |
call.recording.ready | call_id, external_id, links with recording and transcript, status of uploaded or failed | Yes |
callback.scheduled | lead_id, call_id, external_id, callback_datetime, timezone | n/a |
transfer.status is connected, no_answer, voicemail or failed. For agency callbacks, drop external_id and media_pending and read transfer.to_agent.
Agency call.completed, the outcome promptly at hangup:
{
"type": "call.completed",
"data": {
"call": {
"id": "call_01J8…",
"status": "completed",
"direction": "outbound",
"to_number": "+15555551234",
"from_number": "+15555550000",
"agent_id": "agent_01J…",
"disposition": "declined",
"duration_seconds": 73,
"talk_time_seconds": 58,
"answered_at": "2026-07-04T19:29:10Z",
"ended_at": "2026-07-04T19:30:23Z",
"metadata": { "crm_id": "lead-42" }
},
"analysis_pending": true
}
}Agency call.analysis.completed, the AI result plus links to fetch the artifacts:
{
"type": "call.analysis.completed",
"data": {
"call_id": "call_01J8…",
"analysis": {
"summary": "Shopping auto+home bundle; renewal in 3 weeks; currently with Geico. Open to a quote.",
"outcome": "qualified_transfer",
"qualification_score": 0.82,
"qualification_data": { "line_of_business": "auto", "current_carrier": "Geico", "renewal_date": "2026-07-25" }
},
"links": {
"recording": "https://api.entrovox.com/v1/calls/call_01J8…/recording-url",
"transcript": "https://api.entrovox.com/v1/calls/call_01J8…/transcript"
}
}
}Recordings and transcripts arrive as links to API paths, not embedded and not as expiring URLs. Fetch them with your key from Recordings and transcripts. The retry policy in full is in Retries and replay.
Next steps
Until delivery is live, poll the status URL. Read Safe retries and idempotency for the same dedupe habits on the way in.