Outbound Webhooks

Receive call events as signed JSON POSTs: event types, the full payload schema, public share links, signature verification and retries.

Showing instructions for Xebit VoiceCloud.Showing instructions for Xebit VoiceKit, on your own infrastructure. Switch with the selector at the top. Updated 22 October 2026.

Outbound webhooks push call events from Xebit to your server the moment they happen, as JSON in an HTTPS POST. Each delivery is signed so you can prove it came from Xebit.

How to listen for webhooks

  1. Expose a public HTTPS endpoint on your server that accepts POST requests.
  2. Register it under the Xebit VoiceCloud dashboard → Workflows → Webhooks → Add Webhookthe Xebit VoiceKit admin console → Workflows → Webhooks → Add Webhook.
  3. Choose the events you want, for example call.completed and call.failed.
  4. Return 200 OK as soon as the request arrives. Xebit waits up to 8 seconds; after that the attempt counts as failed and a retry is queued.
  5. Do the real processing asynchronously, after you have acknowledged.

Xebit VoiceCloud allows 1 webhook endpoint on the Base plan and up to 5 on Professional and Enterprise plans.

On Xebit VoiceKit, the number of webhook endpoints is set by your deployment's configuration. Your endpoint must be reachable from the network your Xebit VoiceKit cluster runs in; in an air gapped installation that means an address inside the same network.

Example listener:

# Simulate a delivery to test your endpoint.
# The signature here is a placeholder; see "Signature verification" below
# for a runnable example that computes a real v1=<base64> value.
curl -X POST https://your-server.example.com/webhook \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Id: evt_test123" \
  -H "X-Webhook-Timestamp: 1748000000" \
  -H "X-Webhook-Signature: v1=your_expected_hmac_base64" \
  -d '{
    "event_id": "evt_test123",
    "event_type": "call.completed",
    "created_at": "2026-06-01T10:00:00Z",
    "data": {
      "call_id": "call_987654321",
      "status": "completed",
      "call_direction": "outbound",
      "call_to": "+15551234567",
      "call_from": null,
      "call_duration_seconds": 124,
      "credits_consumed": 2,
      "agent_id": "agent_alpha",
      "agent_name": "Priya",
      "call_recording": null,
      "call_details_url": null,
      "share_token": null,
      "call_analytics": {
        "summary": "Customer confirmed appointment.",
        "sentiment": "positive",
        "disposition": "appointment_booked",
        "next_steps": "Send appointment confirmation"
      },
      "extracted_details": {"appointment_date": "2026-06-05"},
      "appointment_details": null,
      "call_transcript": null,
      "call_triggered_at": "2026-06-01T09:58:00Z",
      "scheduled_at": null,
      "completed_at": "2026-06-01T10:00:00Z",
      "error": null,
      "contact_name": "Jordan Lee",
      "contact_email": "jordan@example.com",
      "contact_preferred_language": null,
      "custom_data": null
    }
  }'

When testing on your own machine, a tunnelling tool such as ngrok http 3000 gives you a public HTTPS URL to register.

Event types

EventWhen it fires
call.initiatedAs soon as the call has been successfully handed to your carrier, before it is answered or finished.
call.completedWhen the call ends normally. Carries the full analytics and transcript.
call.failedWhen the call could not be completed for a technical reason: busy, no answer, or a carrier or infrastructure error.
call.disallowedWhen a call is blocked before it is placed, for example because of an insufficient balance or a number outside your calling windows. This is separate from call.failed, which is a technical failure during an attempted call.
call.answered is not a supported event. Only the four events above are delivered.

Payload schema

Every delivery shares the same envelope. The data object holds the event specific payload.

Complete example

JSON
{
  "event_id": "evt_c961fe0c-9cbd-4b7b-855e-0a555205f8f0",
  "event_type": "call.completed",
  "created_at": "2026-06-01T10:00:00.000Z",
  "data": {
    "call_id": "call_987654321",
    "status": "completed",
    "call_direction": "outbound",
    "call_to": "+15551234567",
    "call_from": null,
    "call_duration_seconds": 124,
    "credits_consumed": 2,
    "agent_id": "agent_alpha",
    "agent_name": "Priya",
    "call_recording": "https://media.xebit.ai/recordings/call_987654321.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA.../20260601/s3/aws4_request&X-Amz-Date=20260601T100000Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=examplesig123",
    "call_details_url": null,
    "call_analytics": {
      "summary": "Customer confirmed appointment for June 5th at 2:00 PM.",
      "sentiment": "positive",
      "next_steps": "Send appointment confirmation email.",
      "disposition": "appointment_booked"
    },
    "extracted_details": {
      "appointment_date": "2026-06-05",
      "appointment_time": "2:00 PM",
      "service_type": "Consultation"
    },
    "appointment_details": {
      "appointment_id": "appt_a1b2c3d4e5",
      "start_time": "2026-06-05T14:00:00.000Z",
      "status": "confirmed"
    },
    "call_transcript": "https://media.xebit.ai/transcripts/call_987654321.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA.../20260601/s3/aws4_request&X-Amz-Date=20260601T100000Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=examplesig456",
    "call_triggered_at": "2026-06-01T09:58:00.000Z",
    "scheduled_at": null,
    "completed_at": "2026-06-01T10:00:00.000Z",
    "error": null,
    "contact_name": "Jordan Lee",
    "contact_email": "jordan@example.com",
    "contact_preferred_language": "hindi",
    "custom_data": {
      "campaign_id": "camp_123",
      "lead_id": "lead_456"
    },
    "scheduled_call_id": null
  }
}
JSON
{
  "event_id": "evt_c961fe0c-9cbd-4b7b-855e-0a555205f8f0",
  "event_type": "call.completed",
  "created_at": "2026-06-01T10:00:00.000Z",
  "data": {
    "call_id": "call_987654321",
    "status": "completed",
    "call_direction": "outbound",
    "call_to": "+15551234567",
    "call_from": null,
    "call_duration_seconds": 124,
    "credits_consumed": 2,
    "agent_id": "agent_alpha",
    "agent_name": "Priya",
    "call_recording": "https://<your-object-storage>/recordings/call_987654321.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA.../20260601/s3/aws4_request&X-Amz-Date=20260601T100000Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=examplesig123",
    "call_details_url": null,
    "call_analytics": {
      "summary": "Customer confirmed appointment for June 5th at 2:00 PM.",
      "sentiment": "positive",
      "next_steps": "Send appointment confirmation email.",
      "disposition": "appointment_booked"
    },
    "extracted_details": {
      "appointment_date": "2026-06-05",
      "appointment_time": "2:00 PM",
      "service_type": "Consultation"
    },
    "appointment_details": {
      "appointment_id": "appt_a1b2c3d4e5",
      "start_time": "2026-06-05T14:00:00.000Z",
      "status": "confirmed"
    },
    "call_transcript": "https://<your-object-storage>/transcripts/call_987654321.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA.../20260601/s3/aws4_request&X-Amz-Date=20260601T100000Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=examplesig456",
    "call_triggered_at": "2026-06-01T09:58:00.000Z",
    "scheduled_at": null,
    "completed_at": "2026-06-01T10:00:00.000Z",
    "error": null,
    "contact_name": "Jordan Lee",
    "contact_email": "jordan@example.com",
    "contact_preferred_language": "hindi",
    "custom_data": {
      "campaign_id": "camp_123",
      "lead_id": "lead_456"
    },
    "scheduled_call_id": null
  }
}

By default call_recording and call_transcript are temporary signed storage URLs, valid for 5 minutes from the moment a delivery attempt is sent, and call_details_url and share_token are null. Turn on Public call share to receive stable public links instead (see Public call share links). extracted_details and appointment_details sit at the top level of data, not inside call_analytics.

On Xebit VoiceCloud, recordings and transcripts are held in Xebit's platform storage and the signed URLs point there.

On Xebit VoiceKit, recordings and transcripts are held in the object storage your deployment is configured with, and the signed URLs point to it.

Example: callback scheduled

When the agent books a callback during the conversation (enabled under Agent → Call tab → Enable Callback Scheduling), the call.completed event for that call carries scheduled_call_id, the call_id of the call that will be placed later.

JSON
{
  "event_id": "evt_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "event_type": "call.completed",
  "created_at": "2026-06-01T10:00:00.000Z",
  "data": {
    "call_id": "call_987654321",
    "status": "completed",
    "call_direction": "outbound",
    "call_analytics": {
      "summary": "Customer asked to be called back tomorrow afternoon.",
      "sentiment": "neutral",
      "next_steps": "Agent will call back as scheduled.",
      "disposition": "callback_scheduled"
    },
    "scheduled_call_id": "call_abc123de-f456-7890-abcd-ef1234567890"
  }
}

Example: automatic retry scheduled

When a dial attempt fails or is not answered and Call Retry is set up on the agent, the failed call's call.failed event also carries scheduled_call_id, the call_id of the retry. call.failed never includes call_analytics or a disposition, so this field is the only sign that a retry was booked.

JSON
{
  "event_id": "evt_2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
  "event_type": "call.failed",
  "created_at": "2026-06-01T10:00:00.000Z",
  "data": {
    "call_id": "call_123456789",
    "status": "failed",
    "call_direction": "outbound",
    "error": "SIP status: 480 Temporarily Unavailable",
    "scheduled_call_id": "call_def456gh-i789-0123-defg-hi4567890123"
  }
}

Envelope

NameTypeRequiredDescription
event_idstringYesUnique delivery ID, prefixed evt_. Use it for idempotency.
event_typestringYescall.initiated, call.completed, call.failed or call.disallowed.
created_atstring (ISO 8601)YesWhen the event was generated, for example 2026-06-01T10:00:00.000Z.
dataobjectYesThe event payload: call details and metadata.

Call metadata

NameTypeRequiredDescription
call_idstringYesUnique identifier of the call.
statusstringYescompleted, initiated, failed or disallowed.
call_directionstringYesinbound (received) or outbound (placed).
call_tostring | nullYesNumber dialled. Set for outbound calls, null for inbound.
call_fromstring | nullYesCaller's number. Set for inbound calls, null for outbound.
call_duration_secondsnumberYesTotal call length in seconds.
credits_consumednumber | nullNoBillable units recorded for the call. Only set on call.completed; null on call.initiated, call.failed and call.disallowed, because only completed calls are billed. See Cost Model.
agent_idstring | nullNoID of the agent that handled or was assigned the call.
agent_namestring | nullNoDisplay name of the agent.
errorstring | nullConditionalError message. Only set on call.failed and call.disallowed.
scheduled_call_idstring | nullNocall_id of a new call booked as a direct result of this one: a callback the agent arranged, or an automatic retry. Can appear on call.completed (a callback, or a retryable outcome after the agent connected, such as voicemail) or on call.failed (a retryable SIP level failure before the agent connected, such as no answer). Otherwise null.

Timestamps

NameTypeRequiredDescription
call_triggered_atstring (ISO 8601) | nullNoWhen the call was actually placed.
scheduled_atstring (ISO 8601) | nullNoWhen the call was scheduled for, if it was scheduled through the API.
completed_atstring (ISO 8601) | nullNoWhen the call ended.

Contact information

NameTypeRequiredDescription
contact_namestring | nullNoContact's name, from call set-up or picked up during the call.
contact_emailstring | nullNoContact's email, from call set-up or picked up during the call.
contact_preferred_languagestring | nullNoLanguage the call was held in, from call set-up; null when none was set and the agent's default was used.
custom_dataobject | nullNoKey-value metadata attached when the call was triggered, or null. Handy for linking back to your own IDs or campaigns.

Media and analysis

NameTypeRequiredDescription
call_recordingstring | nullNoTemporary signed URL to the recording audio, valid for 5 minutes from when this delivery attempt was sent; null when there is no recording. Download or process it promptly instead of storing the URL. A retried or manually replayed delivery is re-signed at send time, but the copy shown in the dashboard's Deliveries view is signed once at creation and looks expired after 5 minutes. With Public call share on, this becomes a stable public link.
call_details_urlstring | nullNoPublic, no login URL to an embeddable call details page (Call Details, Insights, Recording & Transcript, Appointments) that is safe to load in an <iframe>. Only sent when Public call share is on; otherwise null, and also null if the call has no resolvable call_id.
share_tokenstring | nullNoThe token embedded in call_details_url, sent again as a plain value so you can call GET /public/call/{call_id}?token={share_token} yourself. null under the same conditions as call_details_url.
call_transcriptstring | array | nullNoNormally a temporary signed URL to the full transcript file, with the same 5 minute expiry, re-signing and Public call share behaviour as call_recording. Falls back to an inline array of utterances only for calls that produced a real time transcript but no transcript file. null when there is no transcript at all.
call_analyticsobject | nullNoAI generated summary, sentiment, next steps and disposition (schema below). null until analysis has finished.

When call_transcript is an inline array, each entry looks like this:

JSON
{ "speaker": "agent", "text": "Hi, this is Priya...", "timestamp": 0.0 }
FieldTypeDescription
speakerstringWho spoke, usually agent or user. Raw diarisation labels such as speaker_0 can appear if speakers were not mapped.
textstringWhat was said.
timestampnumberSeconds from the start of the call.

Switch on Public call share under the Xebit VoiceCloud dashboard → Account Settings → Organisationthe Xebit VoiceKit admin console → Account Settings → Organisation to turn call_details_url (and, where a recording or transcript exists, call_recording and call_transcript) into stable public links instead of short lived signed URLs.

JSON
"call_details_url": "https://voice.xebit.ai/public/call/call_987654321?share_token=8f2a1c9d4e7b0a3c6f5d2e1b9a8c7d6e5f4a3b2c",
"share_token": "8f2a1c9d4e7b0a3c6f5d2e1b9a8c7d6e5f4a3b2c"
JSON
"call_details_url": "https://<your-xebit-voicekit-host>/public/call/call_987654321?share_token=8f2a1c9d4e7b0a3c6f5d2e1b9a8c7d6e5f4a3b2c",
"share_token": "8f2a1c9d4e7b0a3c6f5d2e1b9a8c7d6e5f4a3b2c"
  • By default the link never expires. You can set an expiry (1 hour, day, week or month) for newly issued links under the same setting. Links already issued keep the expiry they were created with; a change only affects calls handled afterwards.
  • No login is needed to open it. It is meant to be embedded, for example in an <iframe> inside your own app.
  • call_details_url shows a read only page with the call's Details, Insights, Recording & Transcript and Appointments (if any). Agent Logs never appear on this public page.
  • share_token is the same token as in the call_details_url query string. Use it to call GET /public/call/{call_id}?token={share_token} yourself, which returns the raw JSON (call, insights, transcript, appointments, recording URL). One token unlocks all three public links for a call.
  • With Public call share off (the default), call_details_url and share_token are always null, and call_recording and call_transcript are short lived signed URLs.

To embed the page or build your own player, see Embedding Call Data.

call_analytics schema

JSON
{
  "summary": "Two or three sentence overview of the call",
  "sentiment": "positive|neutral|negative",
  "next_steps": "recommended follow-up action",
  "disposition": "appointment_booked|transferred|not_interested|voicemail|callback_scheduled|ended_by_customer|session_ended"
}
NameTypeRequiredDescription
summarystringYesTwo or three sentences on the outcome and the main points discussed.
sentimentstringYespositive, neutral or negative.
next_stepsstringYesRecommended next action, for example "Schedule follow-up call", "Send proposal" or "No action needed".
dispositionstringYesOutcome code: appointment_booked, transferred, not_interested, voicemail, callback_scheduled, ended_by_customer or session_ended. callback_scheduled always comes with a populated scheduled_call_id.

extracted_details

A top level field alongside call_analytics.

NameTypeRequiredDescription
extracted_detailsobject | nullNoConcrete facts mentioned in the call as key-value pairs. The keys vary from call to call. null if analysis has not finished for this event; otherwise an object, empty ({}) when nothing concrete came up.

Only facts that were actually said appear, and the keys depend on the conversation. For example:

  • The customer gave a date: { "appointment_date": "2026-06-05" }
  • The customer raised a complaint: { "complaint": "Long wait times", "satisfaction_rating": 3 }
  • Nothing concrete was discussed: {}

Iterate over Object.entries(data.extracted_details || {}) instead of reading fixed keys.

appointment_details

A top level field alongside call_analytics.

NameTypeRequiredDescription
appointment_detailsobject | nullConditionalnull unless the call produced a matched appointment. When present it is the raw appointment document, shaped like the appointment object in Appointment Webhooks, not a fixed subset.

Signature verification

Xebit signs every delivery with HMAC-SHA256 so you can confirm it is genuine. Each request carries these headers:

HeaderAlways sent?Signed?Description
Content-TypeYesNoAlways application/json.
User-AgentYesNoAlways Xebit-Webhooks/1.0.
X-Webhook-IdYesNoThe event_id of this delivery. Not part of the signed string.
X-Webhook-TimestampWhen signing is onYesUnix time in seconds when the request was sent. Reject requests that are too old, to guard against replay.
X-Webhook-SignatureWhen signing is onOutputv1=<signature>, computed as below.

Signing is on by default. If it is switched off for an endpoint, X-Webhook-Timestamp and X-Webhook-Signature are not sent at all. Leaving it on is strongly recommended.

Signed payload formula

Text
signed_payload = X-Webhook-Timestamp + "." + raw_request_body

signature = "v1=" + Base64(
  HMAC-SHA256(webhook_secret, signed_payload)
)
  • X-Webhook-Id is not part of the input. Only the timestamp and the raw body are signed, not an id.timestamp.body string.
  • The digest is Base64, not hex.
  • raw_request_body is the exact bytes of the HTTP body, captured before any JSON parsing. Parsing and re-serialising can change whitespace, key order or escaping and break verification.
JavaScript
// Right: read the raw text, then parse
const rawBody = await request.text();
const payload = JSON.parse(rawBody);

// Wrong: re-serialising may not reproduce the bytes that were signed
const parsed = await request.json();
const reserialised = JSON.stringify(parsed);

The webhook secret is shown once, when you create the endpoint, in the form whsec_.... Use it exactly as given. The whsec_ prefix is part of the HMAC key, so do not strip it, and do not Base64 decode the secret.

JavaScript
// Right
crypto.createHmac("sha256", "whsec_abc123...");

// Wrong: the prefix must stay, and the secret is not Base64 encoded
crypto.createHmac("sha256", Buffer.from(secret.replace("whsec_", ""), "base64"));
# Compute a signature and send a signed test request to your own endpoint
SECRET="whsec_your_webhook_secret"
TIMESTAMP="$(date +%s)"
BODY='{"event_id":"evt_test123","event_type":"call.completed","data":{}}'

SIGNATURE=$(printf '%s' "${TIMESTAMP}.${BODY}" \
  | openssl dgst -sha256 -hmac "$SECRET" -binary \
  | base64)

# --data-binary keeps the body byte for byte, which is what was signed
curl -X POST https://your-server.example.com/webhook \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Id: evt_test123" \
  -H "X-Webhook-Timestamp: ${TIMESTAMP}" \
  -H "X-Webhook-Signature: v1=${SIGNATURE}" \
  --data-binary "$BODY"

Common mistakes

  • Including X-Webhook-Id in the signed string.
  • Stripping the whsec_ prefix from the secret.
  • Base64 decoding the secret before using it as the key.
  • Hashing only the JSON body instead of timestamp + "." + raw_body.
  • Using a hex digest instead of Base64.
  • Parsing and re-serialising the JSON before verifying.
  • Comparing without the v1= prefix.

Implementation best practices

  • Acknowledge at once: return 200 OK within 8 seconds, before doing any real work.
  • Process asynchronously: run slow jobs, such as CRM sync, in a background worker after acknowledging.
  • Be idempotent: retries reuse the same event_id, so use it to skip duplicates.
  • Stay secure: verify signatures with a constant time comparison, and use HTTPS endpoints only (enforced at registration).
  • Retries: a failed delivery (non 2xx response, timeout or connection error) is attempted up to 5 times in total: immediately, then after 30 seconds, 2 minutes, 10 minutes and 1 hour.
  • Auto-disable: an endpoint is switched off automatically after 50 consecutive failed attempts (retries included) with no success in between. Re-enable it from the Xebit VoiceCloud dashboardthe Xebit VoiceKit admin console once it is healthy.