Webhook Payloads

This page documents the structure of webhook payloads sent by Vocobase when events occur.

Headers

Every webhook request includes these headers:

Header	Description
`Content-Type`	`application/json`
`X-Webhook-Signature`	HMAC-SHA256 signature: `sha256=<hex>`
`X-Webhook-Timestamp`	ISO 8601 timestamp when the event was sent

Event types

Branch on the top-level event field. These are the values accepted in an endpoint’s events allowlist — see Scoping & Event Filtering.

Event	Fired when
`session.completed`	A session finished and the post-call pipeline is done
`call.status.updated`	Telephony call status changed
`call.transferred`	The call was handed to a human or another number
`whatsapp.message.sent`	An outbound WhatsApp message was accepted by the provider
`whatsapp.message.failed`	An outbound WhatsApp message could not be sent
`whatsapp.message.status_updated`	Delivery or read receipt for a WhatsApp message

Six event types, and that is the complete list. GET /api/v2/config/webhooks returns the same set as data.available_events, so you can read it from the API rather than hard-coding it. webhook.test is fired only by the test endpoint and is not a valid allowlist value — it always reaches the endpoint being tested. Handle or ignore it explicitly.

How a failed session surfaces

A session that ends in a terminal failure — carrier no-answer, busy, rejected, or a bot that never started — is delivered as session.completed, not as a separate failure event. Every session-terminal path builds its payload through the same builder, which always emits event: "session.completed", including the explicit failure path. Branch on the payload, not on the event name:

Signal	Successful session	Failed session
`data.duration_seconds`	Actual bot-leg duration	`0`
`data.credits_used`	Credits deducted	`0`
`data.transcript`	Array of turns	`null`
`data.recording_url`	Presigned URL, or `null` if recording was off	`null`
`data.extraction`	Present when the agent has a Custom Analysis config	Absent
`data.call.status`	`completed`	`failed`, `no_answer`, `busy`, or `canceled`

data.call.status is the reliable discriminator for telephony sessions. For WebRTC sessions there is no call object at all, so use duration_seconds and transcript.

session.failed was previously published in this catalog with no producer behind it. It has been removed, and it is no longer accepted in an endpoint’s events allowlist — sending it now returns 400 VALIDATION_ERROR. Existing allowlists that contained it were stripped of it automatically; an endpoint left with an empty allowlist receives every event type.

inbound.route (below) is a pre-answer routing callback with its own headers and a required response body. It is not part of this event stream and cannot be subscribed to.

Event: `webhook.test`

Sent by POST /api/v2/config/webhooks/{id}/test. Signed and retried exactly like a real event, so receiving it confirms your URL, TLS, and signature verification all work end to end.

{
  "event": "webhook.test",
  "timestamp": "2026-05-25T10:30:00.000Z",
  "data": {
    "endpoint_id": "12345678-abcd-1234-abcd-123456789012",
    "label": "prod",
    "agent_id": null,
    "message": "This is a test event from Vocobase. If you received it, your endpoint and signature verification are wired correctly."
  }
}

agent_id is the endpoint’s scope: null for an account-wide endpoint, the agent’s id for an agent-scoped one.

Event: `inbound.route`

This event is sent when an account-configured pre-answer policy is available for a Vobiz or Plivo inbound call.

Payload structure

{
  "event": "inbound.route",
  "version": "2026-07-04",
  "provider": "plivo",
  "call": {
    "provider_call_id": "call-id",
    "from_number": "+919999999999",
    "to_number": "+918888888888"
  },
  "phone_number": {
    "id": "f1a2c3d4-1111-2222-3333-444455556666",
    "number": "+918888888888"
  },
  "agent": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Headers

Inbound route webhooks for this feature use feature-specific headers:

Header	Description
`Content-Type`	`application/json`
`X-Vocobase-Event`	`inbound.route`
`X-Vocobase-Timestamp`	Unix milliseconds when the payload was sent
`X-Vocobase-Signature`	`v1=<hex-hmac>`

Response contract

Accounts return JSON with an action value:

ANSWER_WITH_AI
SELECT_AGENT
TRANSFER
REJECT

When action is TRANSFER, to_number must be E.164. When action is SELECT_AGENT, agent_id must be set. Vocobase records each resolved route decision for your own observability. Query GET /api/v2/inbound-route-decisions to inspect action, source, webhook status, webhook latency, failure reason, transfer target, and created session or phone-call IDs.

Event: `call.status.updated`

Sent whenever Vocobase learns that a telephony call moved to a new meaningful call status. This event is for real-time orchestration: live dashboards, your own dialer queues, and concurrency release. call.status.updated is sent for phone calls only. Browser WebRTC sessions do not have a carrier call leg and therefore do not emit this event.

Payload structure

{
  "event": "call.status.updated",
  "timestamp": "2026-03-15T14:30:05.000Z",
  "data": {
    "call_id": "c1234567-abcd-1234-abcd-123456789012",
    "session_id": "s1234567-abcd-1234-abcd-123456789012",
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "agent_name": "Sales Assistant",
    "client_reference_id": "lead-9821",
    "direction": "outbound",
    "from_number": "+14155551234",
    "to_number": "+919876543210",
    "status": "ringing",
    "disposition": null,
    "answered_by": null,
    "hangup_cause": null,
    "hangup_source": null,
    "previous_status": "pending",
    "terminal": false,
    "concurrency_released": false,
    "account_concurrency": {
      "limit": 10,
      "active": 4,
      "remaining": 6
    },
    "provider": "twilio",
    "provider_status": "ringing",
    "provider_event": "ringing",
    "occurred_at": "2026-03-15T14:30:05.000Z"
  }
}

Field reference

Field	Type	Description
`event`	string	Always `"call.status.updated"`
`timestamp`	string (ISO 8601)	When Vocobase created the webhook event
`data.call_id`	string (UUID)	Unique Vocobase call identifier
`data.session_id`	string (UUID) or null	Associated session identifier. Normally present for calls started through `POST /calls/start`.
`data.agent_id`	string (UUID)	The agent assigned to the call
`data.agent_name`	string or null	Agent display name
`data.client_reference_id`	string or null	Client-supplied correlation key from `POST /calls/start`, when provided
`data.direction`	string	`outbound` or `inbound`
`data.from_number`	string	Caller phone number
`data.to_number`	string	Destination phone number
`data.status`	string	Normalized Vocobase call status. See Call status values.
`data.disposition`	string or null	Final call outcome when known: `completed`, `voicemail`, `user_hangup_no_speech`, `no_answer`, `busy`, `canceled`, `blocked`, `failed`, or `transferred`. Usually `null` on non-terminal updates.
`data.answered_by`	string or null	Best-known answer classification: `human`, `machine`, `unknown`, or `not_answered`. `machine` indicates an answering machine or voicemail.
`data.hangup_cause`	string or null	Raw normalized carrier hangup cause when available
`data.hangup_source`	string or null	Best-known party or system that ended the call: `caller`, `callee`, `system`, `api`, `carrier`, `error`, or `unknown`
`data.previous_status`	string or null	Previous normalized status, when known
`data.terminal`	boolean	`true` when this status is final for the carrier call leg
`data.concurrency_released`	boolean	`true` when accounts can start the next call in their own queue
`data.account_concurrency`	object or null	Account-wide concurrency snapshot at event time. `limit`/`remaining` are `null` for unlimited accounts.
`data.provider`	string or null	Telephony provider: `twilio`, `plivo`, `vobiz`, `tata_smartflo`, `voicelink`, `sip`, `mcube`, or `exotel`
`data.provider_status`	string or null	Raw provider status value when available
`data.provider_event`	string or null	Raw provider event name when available
`data.occurred_at`	string (ISO 8601)	When the status transition was recorded. Not an end-of-call timestamp — see the warning below.

Do not build a call record from call.status.updated alone. This event is enqueued from the carrier’s callback, which can arrive several seconds before we have written the call’s final row. On a terminal update that means hangup_cause and hangup_source are frequently still null, and there is no end timestamp on this event at all — occurred_at marks the moment of the state transition, not the end of the call.Use call.status.updated for real-time dialer and concurrency orchestration. Use session.completed for the final record: it is built after the call row is settled and carries call.started_at, call.answered_at, call.ended_at and the final hangup attribution. If you need the record before session.completed arrives, poll GET /calls/{call_id}, which returns started_at and ended_at under those same names. answered_at is currently carried only on session.completed.

Call status values

Vocobase normalizes provider-specific call states into one vocabulary:

Status	Terminal	Releases concurrency	Meaning
`pending`	No	No	Vocobase accepted the call request and is waiting for provider progress
`ringing`	No	No	The callee’s phone is ringing
`in_progress`	No	No	The call was answered and the bot/callee leg is active
`completed`	Yes	Yes	An answered call ended normally
`failed`	Yes	Yes	The provider could not connect or continue the call
`no_answer`	Yes	Yes	The callee did not answer
`busy`	Yes	Yes	The callee line was busy
`canceled`	Yes	Yes	The call was canceled before completion

Provider normalization

Accounts should branch on data.status, not on provider-specific values. Vocobase stores the raw provider value for debugging.

Provider value	Vocobase status
Twilio `initiated`	`pending`
Twilio, Plivo, Vobiz `ringing`	`ringing`
Twilio, Plivo, Vobiz `in-progress`; Twilio call-progress `answered`; VoiceLink `call.answered`	`in_progress`
Twilio, Plivo, Vobiz `completed`; answered VoiceLink terminal call	`completed`
Twilio, Plivo, Vobiz `busy`	`busy`
Twilio, Plivo, Vobiz `no-answer`	`no_answer`
Twilio `canceled`; Plivo/Vobiz `cancel`; VoiceLink canceled classifications	`canceled`
Twilio `failed`; Plivo/Vobiz `timeout`; provider error states	`failed`
Tata Smartflo lifecycle payloads (`call_status` is `Answered` or `Missed`; flat snake_case fields include `call_id`, `uuid`, `hangup_cause`, `start_stamp`, `answer_stamp`, `end_stamp`, `billsec`, `recording_url`, and `direction`)	`Answered` maps to `in_progress` while live and `completed` after hangup; `Missed` maps to `no_answer`; terminal carrier/error causes map to `busy`, `canceled`, or `failed`

External queue orchestration

If you run your own dialer, use call.status.updated to manage slots:

function handleVocobaseWebhook(event) {
  if (event.event === "call.status.updated") {
    const update = event.data;

    updateDialerCall(update.call_id, update.status);

    if (update.concurrency_released) {
      startNextQueuedCall();
    }

    return;
  }

  if (event.event === "session.completed") {
    saveTranscriptAndRecording(event.data);
  }
}

Do not wait for session.completed to release a dialer slot. session.completed is the final rich result after transcript, recording, billing, and extraction processing.

Event: `session.completed`

Sent when a Vocobase session has reached final post-call processing. For telephony calls, this happens after the call leg ends and the bot/session pipeline has persisted transcript, recording metadata, billing, variables, and extraction results.

Payload structure

{
  "event": "session.completed",
  "timestamp": "2026-03-15T14:32:08.000Z",
  "data": {
    "session_id": "s1234567-abcd-1234-abcd-123456789012",
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "agent_name": "Sales Assistant",
    "duration_seconds": 127,
    "credits_used": 2.12,
    "processing_complete": true,
    "pipeline_completed_at": "2026-03-15T14:32:08.000Z",
    "transcript": [
      {
        "role": "bot",
        "content": "Hello! Thanks for taking my call. How can I help you today?",
        "timestamp": "2026-03-15T14:30:01.000Z"
      },
      {
        "role": "user",
        "content": "Hi, I'm interested in your enterprise plan.",
        "timestamp": "2026-03-15T14:30:04.500Z"
      },
      {
        "role": "bot",
        "content": "Great choice! Our enterprise plan includes unlimited agents, priority support, and custom voice training.",
        "timestamp": "2026-03-15T14:30:05.200Z"
      }
    ],
    "recording_url": "https://downloads.example.com/recordings/rec_abc123.wav?signature=...",
    "variables": {
      "callee_name": "Sajal",
      "mobile_number": "+919876543210"
    },
    "extraction": {
      "status": "success",
      "values": {
        "interested": true,
        "callback_at": "2026-05-01T15:00:00Z",
        "outcome": "callback_requested"
      },
      "model": "vocobase-managed",
      "extractedAt": "2026-03-15T14:32:09.840Z",
      "latencyMs": 1840,
      "attempts": 1
    },
    "call": {
      "call_id": "c1234567-abcd-1234-abcd-123456789012",
      "client_reference_id": "lead-9821",
      "from_number": "+14155551234",
      "to_number": "+919876543210",
      "direction": "outbound",
      "status": "completed",
      "disposition": "completed",
      "answered_by": "human",
      "started_at": "2026-03-15T14:30:01.000Z",
      "answered_at": "2026-03-15T14:30:09.400Z",
      "ended_at": "2026-03-15T14:32:05.200Z",
      "hangup_cause": "NORMAL_CLEARING",
      "hangup_source": "callee",
      "transferred": false,
      "transferred_at": null,
      "transfer_target": null
    }
  }
}

Field reference

Field	Type	Description
`event`	string	Always `"session.completed"`
`timestamp`	string (ISO 8601)	When the webhook was sent
`data`	object	Event data (see below)

Data object fields

Field	Type	Description
`session_id`	string (UUID)	Unique session identifier
`agent_id`	string (UUID)	The agent that handled the call
`agent_name`	string	Agent display name at time of call
`duration_seconds`	integer	Call duration in seconds
`credits_used`	number	Credits deducted for this call
`processing_complete`	boolean	`true` when post-call processing has finished. Always `true` on the webhook payload itself. Use it when polling `GET /calls/{id}` to tell final results from in-progress processing.
`pipeline_completed_at`	string (ISO 8601) or null	Timestamp when post-call processing finished. Non-null on the webhook. `null` when polling `GET /calls/{id}` and processing has not completed yet, or on older sessions that pre-date this field.
`transcript`	array or null	Ordered list of conversation turns (see below). `null` when the bot never ran — see How a failed session surfaces.
`recording_url`	string or null	Presigned URL for the call recording. `null` if recording was not enabled. URL is valid for 7 days. If it expires, mint a fresh one with `GET /calls/{call_id}/recording-url`.
`variables`	object	Pre-call variable values that were substituted into the agent’s prompt and greeting. Empty object `{}` when no variables were supplied. Echoed for your own audit.
`extraction`	object or absent	Post-call extraction result, present only when the agent has a Custom Analysis config defined. Status is `success`, `failed`, or `skipped` (no transcript). Values are typed per the agent’s config; missing keys are emitted as `null`. See Post-call Extraction below.
`call`	object or absent	Call metadata. Present only for telephony sessions started via `POST /calls/start`. Omitted entirely for browser WebRTC sessions started via `POST /sessions/webrtc` (no associated phone call).
`call.call_id`	string (UUID)	Unique call identifier
`call.client_reference_id`	string or null	Client-supplied correlation key from `POST /calls/start`, when provided. Same key and value as on `call.status.updated`.
`call.from_number`	string	Caller phone number (E.164)
`call.to_number`	string	Destination phone number (E.164)
`call.direction`	string	`"outbound"`
`call.status`	string	Final call lifecycle/carrier status at the time `session.completed` is emitted. Voicemail is exposed through `call.disposition`, not `call.status`.
`call.disposition`	string or null	Final call outcome: `completed`, `voicemail`, `user_hangup_no_speech`, `no_answer`, `busy`, `canceled`, `blocked`, `failed`, or `transferred`.
`call.answered_by`	string or null	Best-known answer classification: `human`, `machine`, `unknown`, or `not_answered`. `machine` indicates an answering machine or voicemail.
`call.started_at`	string (ISO 8601)	When the call leg was created — the moment Vocobase handed the dial to the carrier. Always present.
`call.answered_at`	string (ISO 8601) or null	When the callee picked up. `null` for calls that were never answered (`no_answer`, `busy`, `canceled`) — there was no media path, so there is no answer time.
`call.ended_at`	string (ISO 8601) or null	When the call leg was torn down. `null` only if the leg was never closed out (a stuck call the reaper has not yet finalized). This is the authoritative end-of-call timestamp — see the note below.
`call.hangup_cause`	string or null	Raw normalized carrier hangup cause when available. Same value and same key as on `call.status.updated`.
`call.hangup_source`	string or null	Best-known party or system that ended the call: `caller`, `callee`, `system`, `api`, `carrier`, `error`, or `unknown`. Same value and same key as on `call.status.updated`. Not reported by every carrier — see Hangup attribution coverage below.
`call.transferred`	boolean	`true` if the bot handed the call off to a human via the cold-transfer flow. See Transferred calls below.
`call.transferred_at`	string (ISO 8601) or null	When the bot left the room and the carrier began bridging the caller to the human. `null` for non-transferred calls.
`call.transfer_target`	string or null	E.164 destination the caller was bridged to. `null` for non-transferred calls.

Transcript entry format

Each entry in the transcript array has:

Field	Type	Description
`role`	string	`"user"` or `"bot"`
`content`	string	What was said
`timestamp`	string (ISO 8601)	When this turn occurred

recording_url is a presigned URL valid for 7 days from the moment the webhook fires. Download and persist the recording on your side if you need long-term retention. If the URL expires before you can download it, call GET /calls/{call_id}/recording-url to mint a fresh one with another 7-day window.

Hangup attribution coverage

hangup_source and hangup_cause come from the carrier’s Call Detail Record, which we fetch after the hangup callback. Not every carrier exposes one. On carriers that do not, both fields are null on every call — including calls that ended perfectly normally. Treat null as “this carrier does not report it,” never as “nobody hung up” and never as an error. In particular, do not infer an abandoned or failed call from a null hangup_source; use call.disposition for outcome logic and hangup_source only as supporting detail when present. "unknown" is distinct from null: it means the carrier answered the question and did not know. Both are non-actionable, but only null means the signal was never available. If your account needs teardown attribution and you are seeing null across the board, contact support — the coverage gap is per-carrier, and switching the number’s provider is usually what changes it.

Final call status on `session.completed`

call.status in session.completed reflects the final known carrier state. For real-time intermediate statuses, use call.status.updated.

Status	Description
`completed`	Call connected and ended normally
`failed`	Call could not be placed (provider error)
`no_answer`	Recipient did not answer
`busy`	Recipient’s line was busy
`canceled`	Call was canceled before connecting

Call disposition values

Disposition	Description
`completed`	Human-answered call completed normally
`voicemail`	Carrier AMD or bot-side detection classified the answer as voicemail
`user_hangup_no_speech`	The callee answered, then hung up quickly before speaking
`no_answer`	Recipient did not answer
`busy`	Recipient’s line was busy
`canceled`	Call was canceled before connecting
`blocked`	Carrier/provider rejected or blocked the call
`failed`	Call failed or ended with an unmapped error outcome
`transferred`	Call was handed off to a human via the cold-transfer flow

Transferred calls

When an agent transfers a live call to a human:

The bot speaks the configured announcement (transfer_message).
Vocobase transfers the caller to transfer_target.
The session.completed webhook includes transfer metadata.

The session.completed webhook fires once the bot leg ends, not when the caller eventually hangs up with the human. This means:

duration_seconds reflects only the bot leg (caller-on-with-bot time).
recording_url, when present, is the bot-leg recording. The human side is not recorded.
call.transferred is true; call.transferred_at is the redirect moment; call.transfer_target is the destination E.164.

Use call.transferred as the cheap discriminator if your downstream automation needs to distinguish a transferred call from a normal hangup.

{
  "call": {
    "call_id": "c1234567-abcd-1234-abcd-123456789012",
    "from_number": "+14155551234",
    "to_number": "+919876543210",
    "direction": "outbound",
    "status": "completed",
    "disposition": "completed",
    "answered_by": "human",
    "transferred": true,
    "transferred_at": "2026-05-06T14:32:11.000Z",
    "transfer_target": "+14155559999"
  }
}

Event: `call.transferred`

Fired the moment a live call is handed off to a human, from the transfer route on a successful transfer. The call is still in progress when this fires, so there is no duration, disposition, transcript, or recording yet — transferred_at and transfer_target are the payload. Emitted for phone calls only. Browser WebRTC sessions cannot be transferred.

Payload structure

{
  "event": "call.transferred",
  "timestamp": "2026-05-06T14:32:11.000Z",
  "data": {
    "session_id": "s1234567-abcd-1234-abcd-123456789012",
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "agent_name": "Sales Assistant",
    "call": {
      "call_id": "c1234567-abcd-1234-abcd-123456789012",
      "client_reference_id": "lead-9821",
      "from_number": "+14155551234",
      "to_number": "+919876543210",
      "direction": "outbound",
      "transferred": true,
      "transferred_at": "2026-05-06T14:32:11.000Z",
      "transfer_target": "+14155559999"
    }
  }
}

Field reference

Field	Type	Description
`event`	string	Always `"call.transferred"`
`timestamp`	string (ISO 8601)	When Vocobase created the webhook event
`data.session_id`	string (UUID)	The session whose call was transferred
`data.agent_id`	string (UUID)	The agent that handed off the call
`data.agent_name`	string or null	Agent display name
`data.call.call_id`	string (UUID)	Unique call identifier
`data.call.client_reference_id`	string or null	Client-supplied correlation key from `POST /calls/start`, when provided
`data.call.from_number`	string	Caller phone number (E.164)
`data.call.to_number`	string	Destination phone number (E.164)
`data.call.direction`	string	`outbound` or `inbound`
`data.call.transferred`	boolean	Always `true` on this event
`data.call.transferred_at`	string (ISO 8601) or null	When the bot left the room and the carrier began bridging
`data.call.transfer_target`	string or null	E.164 destination the caller was bridged to

call.transferred does not replace session.completed. A transferred call still emits session.completed when the bot leg ends, with call.transferred: true. Use call.transferred when you need to react at hand-off time; use session.completed for the final record.

Events: `whatsapp.message.*`

Three events cover outbound WhatsApp messaging. They share one payload shape and differ only in the event value and the data.status that triggered them.

Event	Fired when
`whatsapp.message.sent`	The message was accepted by the provider
`whatsapp.message.failed`	The provider reported a terminal failure
`whatsapp.message.status_updated`	A non-failure delivery status advanced (delivered, read)

Payload structure

{
  "event": "whatsapp.message.status_updated",
  "data": {
    "message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgS",
    "session_id": "s1234567-abcd-1234-abcd-123456789012",
    "to_number": "+919876543210",
    "template_ref": "callback_confirmation/en",
    "status": "DELIVERED",
    "provider": "AISENSY",
    "ts": "2026-05-25T10:30:00.000Z"
  }
}

These payloads have no top-level timestamp. Every other event in this reference carries one; the WhatsApp events carry data.ts instead. If your handler reads event.timestamp unconditionally it will get undefined here. Fall back to data.ts, or to the X-Webhook-Timestamp header, which is sent on every delivery including these.

Field reference

Field	Type	Description
`event`	string	One of the three `whatsapp.message.*` values above
`data.message_id`	string or null	Provider message id. `null` until the provider has assigned one.
`data.session_id`	string (UUID) or null	The session the message belongs to. `null` for messages not tied to a session.
`data.to_number`	string	Destination number
`data.template_ref`	string	Campaign name, or `name/lang` for a template message
`data.status`	string	Delivery status, uppercase: `QUEUED`, `SENT`, `DELIVERED`, `READ`, `FAILED`, or `SKIPPED`
`data.error_code`	string or absent	Provider error code. Present only when the log row carries one — typically on `whatsapp.message.failed`.
`data.provider`	string	Messaging provider: `AISENSY` or `INTERAKT`
`data.ts`	string (ISO 8601)	When Vocobase built the event

data.status is uppercase here, unlike call.status.updated and session.completed, whose call statuses are lowercased. Compare case-insensitively if you normalize statuses across event types.

Scope resolution: the messaging log has no agent of its own, so the agent is resolved through the message’s session when there is one. A message with no session is agentless and therefore reaches account-wide endpoints only — an agent-scoped endpoint will never see it. See Scoping & Event Filtering.

Polling `GET /calls/{id}` vs webhook

Both the webhook and GET /api/v2/calls/{id} return the same data shape, so an account that can’t accept inbound webhooks (or wants to reconcile dropped deliveries) can poll the GET endpoint instead. A call can appear completed before all transcript, recording, and extraction fields are ready. The processing_complete boolean tells you when the response is final:

status                processing_complete    meaning
─────────────────────────────────────────────────────────────────────────────
pending/ringing/
in_progress           false                  call still in progress
completed             false                  call ended; post-call processing still running
completed             true                   final — transcript / recording / extraction are stable
failed/no_answer/
busy/canceled         true                   terminal failure; no bot transcript

Recommended polling pattern

async function fetchUntilReady(callId) {
  while (true) {
    const { data } = await vocobase.get(`/calls/${callId}`);
    if (data.session?.processing_complete === true) return data;
    if (data.status === 'failed' || data.status === 'no_answer' || data.status === 'busy') return data;
    await sleep(30_000);
  }
}

In practice the session.completed webhook will reach you before polling kicks in — polling is the fallback for accounts that can’t accept inbound webhooks, or for reconciliation after a delivery failure.

For sessions created before this field shipped, pipeline_completed_at will be null permanently. Treat null + status: completed on an older row as “final” — those rows pre-date the signal.

Post-call extraction

When the agent has a Custom Analysis config defined, the platform runs an LLM extraction over the transcript after every completed call and ships the result inline in the same session.completed webhook — no second webhook to handle. Configure extraction via the dashboard’s “Variables & Analytics” tab on the agent editor or via PUT /api/v2/agent/:id with extraction_config.

Extraction object structure

{
  "status": "success",
  "values": {
    "interested": true,
    "callback_at": "2026-05-01T15:00:00Z",
    "outcome": "callback_requested"
  },
  "model": "vocobase-managed",
  "extractedAt": "2026-03-15T14:32:09.840Z",
  "latencyMs": 1840,
  "attempts": 1
}

Field	Type	Description
`status`	string	`success`, `failed`, or `skipped`
`values`	object or absent	Extracted fields, typed per the agent’s `extraction_config.keys`. Missing fields are emitted as `null`. Absent entirely when `status != 'success'`.
`error`	string or absent	Failure reason — present only when `status === 'failed'`
`model`	string	Opaque extraction model identifier. Do not branch business logic on this value.
`extractedAt`	string (ISO 8601)	When extraction ran
`latencyMs`	integer	LLM latency in milliseconds
`attempts`	integer	Number of attempts (1 = success on first try; 2-3 = retried)

Extraction failures never block webhook delivery. The unified payload always ships with extraction.status indicating outcome — accounts that need extraction values can branch on status === 'success', accounts that just need transcript + recording can ignore the field.

Replay extraction against a past session

If you edit extraction_config and want to backfill an existing session, call POST /api/v2/calls/{call_id}/extract with { "dry_run": false }. Optional dry_run: true returns the result without persisting. The replay uses the agent’s current config (not the config at original-call time).

Pre-call variables

The variables field on every webhook echoes the per-call values that were substituted into the agent’s prompt and greeting. Configure variable names via the dashboard “Variables & Analytics” tab or PUT /api/v2/agent/:id with variables: ["callee_name", "mobile_number"]. Supply per-call values via POST /api/v2/calls/start body field variables: { callee_name: "Sajal" }. Missing values render as empty strings — the platform never errors on missing variables.

​Webhook Payloads

​Headers

​Event types

​How a failed session surfaces

​Event: webhook.test

​Event: inbound.route

​Payload structure

​Headers

​Response contract

​Event: call.status.updated

​Payload structure

​Field reference

​Call status values

​Provider normalization

​External queue orchestration

​Event: session.completed

​Payload structure

​Field reference

​Data object fields

​Transcript entry format

​Hangup attribution coverage

​Final call status on session.completed

​Call disposition values

​Transferred calls

​Event: call.transferred

​Payload structure

​Field reference

​Events: whatsapp.message.*

​Payload structure

​Field reference

​Polling GET /calls/{id} vs webhook

​Recommended polling pattern

​Post-call extraction

​Extraction object structure

​Replay extraction against a past session

​Pre-call variables

​Next steps

Webhook Setup

Error Handling

Webhook Payloads

Headers

Event types

How a failed session surfaces

Event: `webhook.test`

Event: `inbound.route`

Payload structure

Headers

Response contract

Event: `call.status.updated`

Payload structure

Field reference

Call status values

Provider normalization

External queue orchestration

Event: `session.completed`

Payload structure

Field reference

Data object fields

Transcript entry format

Hangup attribution coverage

Final call status on `session.completed`

Call disposition values

Transferred calls

Event: `call.transferred`

Payload structure

Field reference

Events: `whatsapp.message.*`

Payload structure

Field reference

Polling `GET /calls/{id}` vs webhook

Recommended polling pattern

Post-call extraction

Extraction object structure

Replay extraction against a past session

Pre-call variables

Next steps