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
- Expose a public HTTPS endpoint on your server that accepts POST requests.
- Register it under the Xebit VoiceCloud dashboard → Workflows → Webhooks → Add Webhookthe Xebit VoiceKit admin console → Workflows → Webhooks → Add Webhook.
- Choose the events you want, for example
call.completedandcall.failed. - Return
200 OKas soon as the request arrives. Xebit waits up to 8 seconds; after that the attempt counts as failed and a retry is queued. - 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
}
}'from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route("/webhook", methods=["POST"])
def webhook():
event = request.get_json()
event_type = event.get("event_type")
data = event.get("data", {})
print(f"Received {event_type} ({event.get('event_id')})")
if event_type == "call.completed":
print(f"Call {data.get('call_id')} lasted {data.get('call_duration_seconds')}s")
print("Summary:", (data.get("call_analytics") or {}).get("summary"))
# call_transcript is normally a signed URL that expires after 5 minutes,
# so fetch it now. It is an inline list only for calls that never
# produced a transcript file.
transcript = data.get("call_transcript")
if isinstance(transcript, str):
print("Transcript URL (valid 5 min):", transcript)
elif isinstance(transcript, list):
print(f"Inline transcript with {len(transcript)} utterances")
# Acknowledge quickly; hand slow work to a background job
return jsonify({"status": "ok"}), 200
if __name__ == "__main__":
app.run(port=3000)const express = require("express");
const app = express();
app.use(express.json());
app.post("/webhook", async (req, res) => {
// Acknowledge first, then do the work
res.status(200).send("OK");
const { event_id, event_type, data } = req.body;
console.log(`Received ${event_type} (${event_id})`);
if (event_type === "call.completed") {
const { call_id, call_duration_seconds, call_analytics, call_transcript } = data;
console.log(`Call ${call_id} lasted ${call_duration_seconds}s`);
console.log(`Summary: ${call_analytics?.summary}`);
console.log(`Sentiment: ${call_analytics?.sentiment}`);
// Normally a signed URL valid for 5 minutes; an inline array only when
// the call never produced a transcript file.
if (typeof call_transcript === "string") {
console.log(`Transcript URL (valid 5 min): ${call_transcript}`);
} else if (Array.isArray(call_transcript)) {
console.log(`Inline transcript: ${call_transcript.length} utterances`);
}
}
});
app.listen(3000, () => console.log("Listening on port 3000"));When testing on your own machine, a tunnelling tool such as ngrok http 3000 gives you a public HTTPS URL to register.
Event types
| Event | When it fires |
|---|---|
call.initiated | As soon as the call has been successfully handed to your carrier, before it is answered or finished. |
call.completed | When the call ends normally. Carries the full analytics and transcript. |
call.failed | When the call could not be completed for a technical reason: busy, no answer, or a carrier or infrastructure error. |
call.disallowed | When 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
{
"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
}
}{
"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.
{
"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.
{
"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
| Name | Type | Required | Description |
|---|---|---|---|
event_id | string | Yes | Unique delivery ID, prefixed evt_. Use it for idempotency. |
event_type | string | Yes | call.initiated, call.completed, call.failed or call.disallowed. |
created_at | string (ISO 8601) | Yes | When the event was generated, for example 2026-06-01T10:00:00.000Z. |
data | object | Yes | The event payload: call details and metadata. |
Call metadata
| Name | Type | Required | Description |
|---|---|---|---|
call_id | string | Yes | Unique identifier of the call. |
status | string | Yes | completed, initiated, failed or disallowed. |
call_direction | string | Yes | inbound (received) or outbound (placed). |
call_to | string | null | Yes | Number dialled. Set for outbound calls, null for inbound. |
call_from | string | null | Yes | Caller's number. Set for inbound calls, null for outbound. |
call_duration_seconds | number | Yes | Total call length in seconds. |
credits_consumed | number | null | No | Billable 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_id | string | null | No | ID of the agent that handled or was assigned the call. |
agent_name | string | null | No | Display name of the agent. |
error | string | null | Conditional | Error message. Only set on call.failed and call.disallowed. |
scheduled_call_id | string | null | No | call_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
| Name | Type | Required | Description |
|---|---|---|---|
call_triggered_at | string (ISO 8601) | null | No | When the call was actually placed. |
scheduled_at | string (ISO 8601) | null | No | When the call was scheduled for, if it was scheduled through the API. |
completed_at | string (ISO 8601) | null | No | When the call ended. |
Contact information
| Name | Type | Required | Description |
|---|---|---|---|
contact_name | string | null | No | Contact's name, from call set-up or picked up during the call. |
contact_email | string | null | No | Contact's email, from call set-up or picked up during the call. |
contact_preferred_language | string | null | No | Language the call was held in, from call set-up; null when none was set and the agent's default was used. |
custom_data | object | null | No | Key-value metadata attached when the call was triggered, or null. Handy for linking back to your own IDs or campaigns. |
Media and analysis
| Name | Type | Required | Description |
|---|---|---|---|
call_recording | string | null | No | Temporary 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_url | string | null | No | Public, 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_token | string | null | No | The 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_transcript | string | array | null | No | Normally 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_analytics | object | null | No | AI 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:
{ "speaker": "agent", "text": "Hi, this is Priya...", "timestamp": 0.0 }| Field | Type | Description |
|---|---|---|
speaker | string | Who spoke, usually agent or user. Raw diarisation labels such as speaker_0 can appear if speakers were not mapped. |
text | string | What was said. |
timestamp | number | Seconds from the start of the call. |
Public call share links
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.
"call_details_url": "https://voice.xebit.ai/public/call/call_987654321?share_token=8f2a1c9d4e7b0a3c6f5d2e1b9a8c7d6e5f4a3b2c",
"share_token": "8f2a1c9d4e7b0a3c6f5d2e1b9a8c7d6e5f4a3b2c""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_urlshows 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_tokenis the same token as in thecall_details_urlquery string. Use it to callGET /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_urlandshare_tokenare alwaysnull, andcall_recordingandcall_transcriptare short lived signed URLs.
To embed the page or build your own player, see Embedding Call Data.
call_analytics schema
{
"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"
}| Name | Type | Required | Description |
|---|---|---|---|
summary | string | Yes | Two or three sentences on the outcome and the main points discussed. |
sentiment | string | Yes | positive, neutral or negative. |
next_steps | string | Yes | Recommended next action, for example "Schedule follow-up call", "Send proposal" or "No action needed". |
disposition | string | Yes | Outcome 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.
| Name | Type | Required | Description |
|---|---|---|---|
extracted_details | object | null | No | Concrete 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.
| Name | Type | Required | Description |
|---|---|---|---|
appointment_details | object | null | Conditional | null 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:
| Header | Always sent? | Signed? | Description |
|---|---|---|---|
Content-Type | Yes | No | Always application/json. |
User-Agent | Yes | No | Always Xebit-Webhooks/1.0. |
X-Webhook-Id | Yes | No | The event_id of this delivery. Not part of the signed string. |
X-Webhook-Timestamp | When signing is on | Yes | Unix time in seconds when the request was sent. Reject requests that are too old, to guard against replay. |
X-Webhook-Signature | When signing is on | Output | v1=<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
signed_payload = X-Webhook-Timestamp + "." + raw_request_body
signature = "v1=" + Base64(
HMAC-SHA256(webhook_secret, signed_payload)
)X-Webhook-Idis not part of the input. Only the timestamp and the raw body are signed, not anid.timestamp.bodystring.- The digest is Base64, not hex.
raw_request_bodyis 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.
// 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.
// 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"import base64
import hashlib
import hmac
def verify_signature(timestamp: str, raw_body: str, signature: str, secret: str) -> bool:
payload = f"{timestamp}.{raw_body}".encode()
expected = "v1=" + base64.b64encode(
hmac.new(secret.encode(), payload, hashlib.sha256).digest()
).decode()
# constant time, and safe when the lengths differ
return hmac.compare_digest(signature, expected)const crypto = require("crypto");
function verifySignature(secret, timestamp, rawBody, signatureHeader) {
const expected = "v1=" + crypto
.createHmac("sha256", secret)
.update(`${timestamp}.${rawBody}`)
.digest("base64");
const expectedBuf = Buffer.from(expected);
const actualBuf = Buffer.from(signatureHeader || "");
// timingSafeEqual throws on different lengths, so check first
if (expectedBuf.length !== actualBuf.length) return false;
return crypto.timingSafeEqual(expectedBuf, actualBuf);
}
// In a fetch-style handler (header names arrive in lower case)
const timestamp = request.headers.get("x-webhook-timestamp");
const signature = request.headers.get("x-webhook-signature");
const rawBody = await request.text(); // raw text, before any JSON.parse
if (!verifySignature(process.env.XEBIT_WEBHOOK_SECRET, timestamp, rawBody, signature)) {
return new Response("Invalid signature", { status: 401 });
}
const payload = JSON.parse(rawBody);Common mistakes
- Including
X-Webhook-Idin 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 OKwithin 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.