Skip to content

Get outcomes

Webhooks

Signed events pushed to your URL instead of polling. Delivery is a preview: build against the contract, poll for now.

On this page

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

EventWhenAudience
lead.acceptedWe enrolled the leadPartner only
call.startedThe outbound dial was placedBoth
call.answeredThe lead picked up and the AI conversation beganBoth
call.completedAn attempt ended. ProvisionalBoth
call.transferredA warm transfer to a licensed agent has a resultBoth
call.failedAn accepted call could not completeBoth
call.analysis.completedThe post-call summary is ready. Media may still be pendingBoth
call.recording.readyThe recording and transcript are fetchablePartner only
callback.scheduledThe lead asked to be called backPartner only
webhook.testYou asked us to send a testPartner 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-idstringOptional

The event id, stable across retries. Dedupe on it: delivery is at least once.

webhook-timestampstringOptional

Unix seconds when we sent it. Reject a delivery more than 300 seconds off your clock, which stops replays. The libraries enforce this.

webhook-signaturestringOptional

One 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

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.completed can arrive before call.answered. Reconcile against the call's own state, not arrival order.
  • Respond fast. Return 2xx within about five seconds and process asynchronously. A non-2xx or 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:

JSON
{
  "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:

typedataFinal?
lead.acceptedlead, external_idn/a
webhook.testok: trueIgnore
call.started, call.answered, call.failedcall, external_idNo
call.completedcall, external_id, analysis_pending, media_pendingNo
call.transferredcall, external_id, transfer with status, to_number, initiated_at, connected_at, human_talk_secondsTransfer result
call.analysis.completedcall_id, external_id, analysis, links, media_pendingNo, if media_pending
call.recording.readycall_id, external_id, links with recording and transcript, status of uploaded or failedYes
callback.scheduledlead_id, call_id, external_id, callback_datetime, timezonen/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:

JSON
{
  "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:

JSON
{
  "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.

Updated Nov 7, 2026