Webhooks
Webhooks
Signed events pushed to your URL as a lead and its calls move along, so you do not have to poll.
On this page
Overview
We POST a JSON event to your URL. Every event has the same envelope: an id that stays the same across retries, a type, a created_at time, an api_version and a data object that depends on the type.
There are two audiences. Partner subscriptions can receive all 10 events, with the fuller payloads. Agency integrations that set webhook_url on a call can subscribe to the call.* events except call.recording.ready, with leaner payloads; by default they get call.started, call.completed, call.failed and call.transferred. The guide Webhooks covers how to choose events.
Event catalog
Most events are provisional: a later event can change what an earlier one said. Write your records once, on the final event for your audience.
- lead.accepted
- call.started
- call.answered
- call.transferred
- call.completed
- call.analysis.completed
- call.recording.ready
Partners store the result at call.recording.ready. Agency webhook_url callbacks never get it, so call.analysis.completed is their last event once added to webhook_events.
| Event | Fires when | What to do | Final? |
|---|---|---|---|
| lead.accepted | We enrolled the lead | Save the lead id and status URL | Partner: n/aAgency: Not sent |
| call.started | The outbound dial was placed | Optional for partners; on by default for agency callbacks | Partner: ProvisionalAgency: Provisional |
| call.answered | The lead picked up and the AI voice agent began the conversation | Optional. Off by default for partners; agency callbacks opt in with webhook_events | Partner: ProvisionalAgency: Provisional |
| call.failed | An accepted call could not complete | Optional for partners; on by default for agency callbacks | Partner: ProvisionalAgency: Provisional |
| call.completed | An attempt ended | Update the duration and disposition. Provisional | Partner: ProvisionalAgency: Provisional |
| call.transferred | A warm transfer to a licensed agent has a result | Record the transfer result: connected, no_answer, voicemail or failed | Partner: Transfer resultAgency: Transfer result |
| call.analysis.completed | The AI summary and qualification are ready | Store the summary. Partners: media may still be pending. Agency callbacks opt in with webhook_events | Partner: Provisional (media_pending)Agency: Final (opt-in) |
| call.recording.ready | The recording and transcript can be fetched | Write the disposition and media to your system. Final for partners | Partner: FinalAgency: Not sent |
| callback.scheduled | The lead asked to be called back | Show the appointment | Partner: n/aAgency: Not sent |
| webhook.test | You asked us to send a test event | Check your signature code, then ignore it | Partner: IgnoreAgency: Not sent |
Events
One section per event, with the payload we send. IDs and times in the examples are illustrative.
lead.accepted
Partner subscriptions onlyPartner: n/a
Partner only. Entrovox enrolled the lead you posted. Persist lead.id and status_url. data.lead is the full Lead object (the example is abbreviated). Not final.
data carries external_id, lead.
{
"api_version": "2026-09-10",
"created_at": "2026-09-10T18:06:01Z",
"data": {
"external_id": "crm-lead-42",
"lead": {
"id": "lead_01J8",
"status_url": "https://api.entrovox.com/v1/leads/lead_01J8"
}
},
"id": "evt_01J8XYZ",
"type": "lead.accepted"
}call.started
Partner and agencyProvisional
The outbound dial was placed. Not final. Agency webhook_url callbacks carry data exactly as in the example; partner subscriptions add the fields listed in x-partner-data.
Partner data carries call, external_id.
Agency data carries call.
{
"api_version": "2026-09-10",
"created_at": "2026-09-10T18:06:01Z",
"data": {
"call": {
"agent_id": "agent_01J8",
"answered_at": null,
"direction": "outbound",
"disposition": null,
"duration_seconds": null,
"ended_at": null,
"from_number": "+15555550000",
"id": "call_01J8",
"metadata": {
"crm_id": "lead-42"
},
"status": "queued",
"talk_time_seconds": null,
"to_number": "+15555551234"
},
"external_id": "crm-lead-42"
},
"id": "evt_01J8XYZ",
"type": "call.started"
}{
"api_version": "2026-09-10",
"created_at": "2026-09-10T18:06:01Z",
"data": {
"call": {
"agent_id": "agent_01J8",
"answered_at": null,
"direction": "outbound",
"disposition": null,
"duration_seconds": null,
"ended_at": null,
"from_number": "+15555550000",
"id": "call_01J8",
"metadata": {
"crm_id": "lead-42"
},
"status": "queued",
"talk_time_seconds": null,
"to_number": "+15555551234"
}
},
"id": "evt_01J8XYZ",
"type": "call.started"
}call.answered
Partner and agencyProvisional
The lead picked up; the AI conversation began. Not final. Agency webhook_url callbacks carry data exactly as in the example; partner subscriptions add the fields listed in x-partner-data.
Partner data carries call, external_id.
Agency data carries call.
{
"api_version": "2026-09-10",
"created_at": "2026-09-10T18:06:01Z",
"data": {
"call": {
"agent_id": "agent_01J8",
"answered_at": "2026-09-10T18:05:10Z",
"direction": "outbound",
"disposition": null,
"duration_seconds": null,
"ended_at": null,
"from_number": "+15555550000",
"id": "call_01J8",
"metadata": {
"crm_id": "lead-42"
},
"status": "in_progress",
"talk_time_seconds": null,
"to_number": "+15555551234"
},
"external_id": "crm-lead-42"
},
"id": "evt_01J8XYZ",
"type": "call.answered"
}{
"api_version": "2026-09-10",
"created_at": "2026-09-10T18:06:01Z",
"data": {
"call": {
"agent_id": "agent_01J8",
"answered_at": "2026-09-10T18:05:10Z",
"direction": "outbound",
"disposition": null,
"duration_seconds": null,
"ended_at": null,
"from_number": "+15555550000",
"id": "call_01J8",
"metadata": {
"crm_id": "lead-42"
},
"status": "in_progress",
"talk_time_seconds": null,
"to_number": "+15555551234"
}
},
"id": "evt_01J8XYZ",
"type": "call.answered"
}call.failed
Partner and agencyProvisional
An accepted call could not complete (a scheduled call that fails at fire-time, or a provider error). Synchronous rejections like DNC/hours come back on the POST /calls response instead. Not final. Agency webhook_url callbacks carry data exactly as in the example; partner subscriptions add the fields listed in x-partner-data.
Partner data carries call, external_id.
Agency data carries call, error.
{
"api_version": "2026-09-10",
"created_at": "2026-09-10T18:06:01Z",
"data": {
"call": {
"agent_id": "agent_01J8",
"answered_at": "2026-09-10T18:05:10Z",
"direction": "outbound",
"disposition": null,
"duration_seconds": 73,
"ended_at": "2026-09-10T18:06:23Z",
"from_number": "+15555550000",
"id": "call_01J8",
"metadata": {
"crm_id": "lead-42"
},
"status": "failed",
"talk_time_seconds": 58,
"to_number": "+15555551234"
},
"external_id": "crm-lead-42"
},
"id": "evt_01J8XYZ",
"type": "call.failed"
}{
"api_version": "2026-09-10",
"created_at": "2026-09-10T18:06:01Z",
"data": {
"call": {
"agent_id": "agent_01J8",
"answered_at": "2026-09-10T18:05:10Z",
"direction": "outbound",
"disposition": null,
"duration_seconds": 73,
"ended_at": "2026-09-10T18:06:23Z",
"from_number": "+15555550000",
"id": "call_01J8",
"metadata": {
"crm_id": "lead-42"
},
"status": "failed",
"talk_time_seconds": 58,
"to_number": "+15555551234"
},
"error": {
"code": "SIP_ERROR",
"message": "upstream carrier rejected the call"
}
},
"id": "evt_01J8XYZ",
"type": "call.failed"
}call.completed
Partner and agencyProvisional
The call reached a terminal state; carries status + disposition (qualified_transfer | transferred | declined | no_answer | voicemail | callback_scheduled | connected_other). Provisional, not final: summary and media arrive later. Agency webhook_url callbacks carry data exactly as in the example; partner subscriptions add the fields listed in x-partner-data.
Partner data carries analysis_pending, call, external_id, media_pending.
Agency data carries analysis_pending, call.
{
"api_version": "2026-09-10",
"created_at": "2026-09-10T18:06:01Z",
"data": {
"analysis_pending": true,
"call": {
"agent_id": "agent_01J8",
"answered_at": "2026-09-10T18:05:10Z",
"direction": "outbound",
"disposition": "declined",
"duration_seconds": 73,
"ended_at": "2026-09-10T18:06:23Z",
"from_number": "+15555550000",
"id": "call_01J8",
"metadata": {
"crm_id": "lead-42"
},
"status": "completed",
"talk_time_seconds": 58,
"to_number": "+15555551234"
},
"external_id": "crm-lead-42",
"media_pending": true
},
"id": "evt_01J8XYZ",
"type": "call.completed"
}{
"api_version": "2026-09-10",
"created_at": "2026-09-10T18:06:01Z",
"data": {
"analysis_pending": true,
"call": {
"agent_id": "agent_01J8",
"answered_at": "2026-09-10T18:05:10Z",
"direction": "outbound",
"disposition": "declined",
"duration_seconds": 73,
"ended_at": "2026-09-10T18:06:23Z",
"from_number": "+15555550000",
"id": "call_01J8",
"metadata": {
"crm_id": "lead-42"
},
"status": "completed",
"talk_time_seconds": 58,
"to_number": "+15555551234"
}
},
"id": "evt_01J8XYZ",
"type": "call.completed"
}call.transferred
Partner and agencyPartner: Transfer result
A warm transfer to a licensed agent connected (the hot handoff). Fires during the call. Carries the transfer result. Not final. Agency webhook_url callbacks carry data exactly as in the example; partner subscriptions add the fields listed in x-partner-data.
Partner data carries call, external_id, transfer.
Agency data carries call, transfer.
{
"api_version": "2026-09-10",
"created_at": "2026-09-10T18:06:01Z",
"data": {
"call": {
"agent_id": "agent_01J8",
"answered_at": "2026-09-10T18:05:10Z",
"direction": "outbound",
"disposition": "qualified_transfer",
"duration_seconds": 73,
"ended_at": "2026-09-10T18:06:23Z",
"from_number": "+15555550000",
"id": "call_01J8",
"metadata": {
"crm_id": "lead-42"
},
"status": "in_progress",
"talk_time_seconds": 58,
"to_number": "+15555551234"
},
"external_id": "crm-lead-42",
"transfer": {
"connected_at": "2026-09-10T18:05:58Z",
"human_talk_seconds": 41,
"initiated_at": "2026-09-10T18:05:50Z",
"status": "connected",
"to_number": "+15555559999"
}
},
"id": "evt_01J8XYZ",
"type": "call.transferred"
}{
"api_version": "2026-09-10",
"created_at": "2026-09-10T18:06:01Z",
"data": {
"call": {
"agent_id": "agent_01J8",
"answered_at": "2026-09-10T18:05:10Z",
"direction": "outbound",
"disposition": "qualified_transfer",
"duration_seconds": 73,
"ended_at": "2026-09-10T18:06:23Z",
"from_number": "+15555550000",
"id": "call_01J8",
"metadata": {
"crm_id": "lead-42"
},
"status": "in_progress",
"talk_time_seconds": 58,
"to_number": "+15555551234"
},
"transfer": {
"connected_at": "2026-09-10T18:05:58Z",
"initiated_at": "2026-09-10T18:05:50Z",
"status": "connected",
"to_agent": "Jane (Acme Insurance)"
}
},
"id": "evt_01J8XYZ",
"type": "call.transferred"
}call.analysis.completed
Partner and agencyLast event for agency callbacks, once opted inPartner: Provisional (media_pending)
The post-call AI summary, qualification, transcript and recording links are ready (arrives after call.completed). Recording/transcript are links you fetch on demand, so no expiring URLs sit in your webhook logs. For agency webhook_url callbacks this is the last event of the call. Partner subscriptions: not final while media_pending is true; wait for call.recording.ready. Agency webhook_url callbacks carry data exactly as in the example; partner subscriptions add the fields listed in x-partner-data.
Partner data carries analysis, call_id, external_id, links, media_pending.
Agency data carries analysis, call_id, links.
{
"api_version": "2026-09-10",
"created_at": "2026-09-10T18:06:01Z",
"data": {
"analysis": {
"outcome": "qualified_transfer",
"qualification_data": {
"current_carrier": "Geico",
"line_of_business": "auto"
},
"qualification_score": 0.82,
"summary": "Shopping auto+home bundle; renewal in 3 weeks; with Geico."
},
"call_id": "call_01J8",
"external_id": "crm-lead-42",
"links": {
"recording": "https://api.entrovox.com/v1/calls/call_01J8/recording-url",
"transcript": "https://api.entrovox.com/v1/calls/call_01J8/transcript"
},
"media_pending": true
},
"id": "evt_01J8XYZ",
"type": "call.analysis.completed"
}{
"api_version": "2026-09-10",
"created_at": "2026-09-10T18:06:01Z",
"data": {
"analysis": {
"outcome": "qualified_transfer",
"qualification_data": {
"current_carrier": "Geico",
"line_of_business": "auto"
},
"qualification_score": 0.82,
"summary": "Shopping auto+home bundle; renewal in 3 weeks; with Geico."
},
"call_id": "call_01J8",
"links": {
"recording": "https://api.entrovox.com/v1/calls/call_01J8/recording-url",
"transcript": "https://api.entrovox.com/v1/calls/call_01J8/transcript"
}
},
"id": "evt_01J8XYZ",
"type": "call.analysis.completed"
}call.recording.ready
Partner subscriptions onlyFinal for partners
Partner only. The recording and transcript are fetchable. This is the one final event: write your disposition and artifacts to your LMS here. status is uploaded or failed. links are Entrovox API paths (fetch with your API key), not expiring signed URLs. x-final describes the partner contract; x-audience says who receives the event; agency webhook_url callbacks end at call.analysis.completed.
data carries call_id, external_id, links, status.
{
"api_version": "2026-09-10",
"created_at": "2026-09-10T18:06:01Z",
"data": {
"call_id": "call_01J8",
"external_id": "crm-lead-42",
"links": {
"recording": "https://api.entrovox.com/v1/calls/call_01J8/recording-url",
"transcript": "https://api.entrovox.com/v1/calls/call_01J8/transcript"
},
"status": "uploaded"
},
"id": "evt_01J8XYZ",
"type": "call.recording.ready"
}callback.scheduled
Partner subscriptions onlyPartner: n/a
Partner only. The lead asked to be called back. Show the appointment. Not final.
data carries call_id, callback_datetime, external_id, lead_id, timezone.
{
"api_version": "2026-09-10",
"created_at": "2026-09-10T18:06:01Z",
"data": {
"call_id": "call_01J8",
"callback_datetime": "2026-09-11T15:00:00",
"external_id": "crm-lead-42",
"lead_id": "lead_01J8",
"timezone": "America/Chicago"
},
"id": "evt_01J8XYZ",
"type": "callback.scheduled"
}webhook.test
Partner subscriptions onlyPartner: Ignore
Partner only. Sent by POST /v1/webhooks/{id}/test with a real signature so you can confirm verification before live leads. Ignore it as a lead event.
data carries ok.
{
"api_version": "2026-09-10",
"created_at": "2026-09-10T18:06:01Z",
"data": {
"ok": true
},
"id": "evt_01J8XYZ",
"type": "webhook.test"
}Verify signatures
We sign every delivery with Standard Webhooks (standardwebhooks.com), so an off-the-shelf library for your language can verify it. Each request carries three headers.
webhook-idstringOptionalid. Stable across retries, so dedupe on it.webhook-timestampstringOptionalwebhook-signaturestringOptionalv1,<base64 signature> entries. Several appear while a secret is rotated, and a match on any one passes.- The signing secret starts with
whsec_and is shown once. Keep it on your server. - Verify against the raw request body, before any JSON parsing. Re-serializing the JSON breaks the signature.
- Return a 2xx within about five seconds, then process in the background.
With a library
# 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) -> dict:
# Checks webhook-id, webhook-timestamp (300 seconds) and webhook-signature.
# Raises WebhookVerificationError when any of them is wrong.
return wh.verify(raw_body, headers)// 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 timestamp more than 300 seconds off.
return wh.verify(rawBody, headers);
}<?php
// composer require standard-webhooks/standard-webhooks
require 'vendor/autoload.php';
use StandardWebhooks\Webhook;
$wh = new Webhook(getenv('ENTROVOX_WEBHOOK_SECRET')); // whsec_...
function handle(string $rawBody, array $headers) {
// getallheaders() returns "Webhook-Id", so lowercase the names first.
$headers = array_change_key_case($headers, CASE_LOWER);
// Throws on a bad signature or a timestamp more than 300 seconds off.
global $wh;
return $wh->verify($rawBody, $headers);
}
// $event = handle(file_get_contents('php://input'), getallheaders());By hand
Without a library, the HMAC key is the base64-decoded part of your secret after whsec_. Sign {webhook-id}.{webhook-timestamp}.{raw body} exactly, base64-encode the SHA-256 digest, and compare it with each v1, entry in constant time. Reject timestamps outside the 300 second window.
import base64
import hashlib
import hmac
import os
import time
# The key is the base64-decoded part of the secret after "whsec_".
KEY = base64.b64decode(os.environ["ENTROVOX_WEBHOOK_SECRET"].removeprefix("whsec_"))
TOLERANCE_SECONDS = 300
def verify(raw_body: bytes, headers: dict) -> bool:
msg_id = headers["webhook-id"]
timestamp = headers["webhook-timestamp"]
if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
return False
# Sign "{id}.{timestamp}.{raw body}" exactly, with the raw bytes.
signed = msg_id.encode() + b"." + timestamp.encode() + b"." + raw_body
expected = base64.b64encode(hmac.new(KEY, signed, hashlib.sha256).digest()).decode()
# The header holds one or more space-separated "v1,<signature>" entries.
for entry in headers["webhook-signature"].split(" "):
version, _, signature = entry.partition(",")
if version == "v1" and hmac.compare_digest(signature, expected):
return True
return Falseimport { createHmac, timingSafeEqual } from "node:crypto";
// The key is the base64-decoded part of the secret after "whsec_".
const key = Buffer.from(process.env.ENTROVOX_WEBHOOK_SECRET.replace(/^whsec_/, ""), "base64");
const TOLERANCE_SECONDS = 300;
export function verify(rawBody, headers) {
const id = headers["webhook-id"];
const timestamp = headers["webhook-timestamp"];
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) return false;
// Sign "{id}.{timestamp}.{raw body}" exactly, with the raw bytes.
const signed = Buffer.concat([Buffer.from(`${id}.${timestamp}.`), Buffer.from(rawBody)]);
const expected = createHmac("sha256", key).update(signed).digest();
// The header holds one or more space-separated "v1,<signature>" entries.
return headers["webhook-signature"].split(" ").some((entry) => {
const [version, signature = ""] = entry.split(",");
const given = Buffer.from(signature, "base64");
return version === "v1" && given.length === expected.length && timingSafeEqual(given, expected);
});
}<?php
// The key is the base64-decoded part of the secret after "whsec_".
$key = base64_decode(substr(getenv('ENTROVOX_WEBHOOK_SECRET'), strlen('whsec_')));
const TOLERANCE_SECONDS = 300;
function verify(string $rawBody, array $headers): bool {
global $key;
// getallheaders() returns "Webhook-Id", so lowercase the names first.
$headers = array_change_key_case($headers, CASE_LOWER);
$id = $headers['webhook-id'];
$timestamp = $headers['webhook-timestamp'];
if (abs(time() - (int) $timestamp) > TOLERANCE_SECONDS) {
return false;
}
// Sign "{id}.{timestamp}.{raw body}" exactly, with the raw bytes.
$expected = base64_encode(hash_hmac('sha256', "$id.$timestamp.$rawBody", $key, true));
// The header holds one or more space-separated "v1,<signature>" entries.
foreach (explode(' ', $headers['webhook-signature']) as $entry) {
[$version, $signature] = array_pad(explode(',', $entry, 2), 2, '');
if ($version === 'v1' && hash_equals($expected, $signature)) {
return true;
}
}
return false;
}Retries and replay
Acknowledge a delivery with any 2xx within about five seconds. A non-2xx response or a timeout is retried with exponential backoff, about five attempts over a few hours.
- At least once. A retry is the same event with the same
id. Dedupe on it. - Unordered. Under retries
call.completedcan arrive beforecall.answered. Reconcile against the call's own state, not arrival order. - After the last attempt the event is not sent again on its own. Fetch the current state from the lead's status URL, and contact us with the event
idif you need one resent.
To check your signature code before live leads arrive, a partner subscription can ask for a webhook.test event, signed like any other.