Skip to content

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.

A typical transferred lead
  1. lead.accepted
  2. call.started
  3. call.answered
  4. call.transferred
  5. call.completed
  6. call.analysis.completed
  7. 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.

EventFires whenWhat to doFinal?
lead.acceptedWe enrolled the leadSave the lead id and status URLPartner: n/aAgency: Not sent
call.startedThe outbound dial was placedOptional for partners; on by default for agency callbacksPartner: ProvisionalAgency: Provisional
call.answeredThe lead picked up and the AI voice agent began the conversationOptional. Off by default for partners; agency callbacks opt in with webhook_eventsPartner: ProvisionalAgency: Provisional
call.failedAn accepted call could not completeOptional for partners; on by default for agency callbacksPartner: ProvisionalAgency: Provisional
call.completedAn attempt endedUpdate the duration and disposition. ProvisionalPartner: ProvisionalAgency: Provisional
call.transferredA warm transfer to a licensed agent has a resultRecord the transfer result: connected, no_answer, voicemail or failedPartner: Transfer resultAgency: Transfer result
call.analysis.completedThe AI summary and qualification are readyStore the summary. Partners: media may still be pending. Agency callbacks opt in with webhook_eventsPartner: Provisional (media_pending)Agency: Final (opt-in)
call.recording.readyThe recording and transcript can be fetchedWrite the disposition and media to your system. Final for partnersPartner: FinalAgency: Not sent
callback.scheduledThe lead asked to be called backShow the appointmentPartner: n/aAgency: Not sent
webhook.testYou asked us to send a test eventCheck your signature code, then ignore itPartner: 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.

Partner subscription
{
  "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"
}

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"
}

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"
}

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"
}

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"
}

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"
}

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.

Partner subscription
{
  "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.

Partner subscription
{
  "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.

Partner subscription
{
  "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-idstringOptional
The event id. Stable across retries, so dedupe on it.
webhook-timestampstringOptional
Unix seconds when we signed the delivery. Reject one more than 300 seconds from your clock.
webhook-signaturestringOptional
One or more space-separated v1,<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)

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 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.completed can arrive before call.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 id if 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.