Inbound Webhooks
Trigger, cancel or delete calls by POSTing to a secret per-organisation URL, with optional HMAC signing and token rotation.
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.
Inbound webhooks let your other systems make Xebit act, for example start a call, by sending an authorised POST to a URL unique to your organisation. Nothing beyond the URL is needed, which suits tools that cannot store an API key.
| Inbound webhook | REST API | |
|---|---|---|
| Best for | No-code tools, CRMs and automation platforms | Custom applications and backend integrations |
| Authentication | Secret token in the URL | API key in a header |
Endpoint configuration
Each inbound webhook has a secret token that identifies your organisation.
/v1/hooks/{YOUR_SECRET_TOKEN}- Method:
POST - URL:
https://api.voice.xebit.ai/v1/hooks/{YOUR_SECRET_TOKEN} - URL:
https://<your-xebit-voicekit-host>/v1/hooks/{YOUR_SECRET_TOKEN} - Content-Type:
application/json
Making a call through an inbound webhook
- Find your secret token under the Xebit VoiceCloud dashboard → Integrations → Inbound Webhooksthe Xebit VoiceKit admin console → Integrations → Inbound Webhooks.
- Set
actiontocall.createin the body. - Add the contact details:
agent_idandcontact_numberat minimum. - POST the request to your inbound URL.
- A response with a
call_idandstatus: scheduledconfirms the call is on its way.
curl -s -X POST "https://api.voice.xebit.ai/v1/hooks/YOUR_SECRET_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"action": "call.create",
"data": {
"agent_id": "agent_abc_123",
"contact_number": "+919876543210",
"contact_name": "John Doe"
}
}'import os
import requests
BASE_URL = "https://api.voice.xebit.ai/v1"
token = "YOUR_SECRET_TOKEN"
response = requests.post(
f"{BASE_URL}/hooks/{token}",
json={
"action": "call.create",
"data": {
"agent_id": "agent_abc_123",
"contact_number": "+919876543210",
"contact_name": "John Doe"
}
}
)
print(response.status_code, response.json())const BASE_URL = "https://api.voice.xebit.ai/v1";
const token = "YOUR_SECRET_TOKEN";
const response = await fetch(`${BASE_URL}/hooks/${token}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
action: "call.create",
data: {
agent_id: "agent_abc_123",
contact_number: "+919876543210",
contact_name: "John Doe"
}
})
});
console.log(response.status, await response.json());curl -s -X POST "https://<your-xebit-voicekit-host>/v1/hooks/YOUR_SECRET_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"action": "call.create",
"data": {
"agent_id": "agent_abc_123",
"contact_number": "+919876543210",
"contact_name": "John Doe"
}
}'import os
import requests
BASE_URL = "https://<your-xebit-voicekit-host>/v1"
token = "YOUR_SECRET_TOKEN"
response = requests.post(
f"{BASE_URL}/hooks/{token}",
json={
"action": "call.create",
"data": {
"agent_id": "agent_abc_123",
"contact_number": "+919876543210",
"contact_name": "John Doe"
}
}
)
print(response.status_code, response.json())const BASE_URL = "https://<your-xebit-voicekit-host>/v1";
const token = "YOUR_SECRET_TOKEN";
const response = await fetch(`${BASE_URL}/hooks/${token}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
action: "call.create",
data: {
agent_id: "agent_abc_123",
contact_number: "+919876543210",
contact_name: "John Doe"
}
})
});
console.log(response.status, await response.json());Sample response:
{
"data": {
"call_id": "550e8400-e29b-41d4-a716-446655440000",
"scheduled_at": "2026-07-09T05:04:49.122Z",
"status": "scheduled"
}
}Supported actions
Every body has an action and a matching data object.
call.create
Starts an outbound call to one contact with the agent you name.
{
"action": "call.create",
"data": {
"agent_id": "agent_abc_123",
"contact_number": "+919876543210",
"contact_name": "John Doe",
"contact_email": "john@example.com",
"contact_preferred_language": "hindi",
"scheduled_time": "2026-07-15T18:30:00.000Z",
"additional_info": {
"order_id": "ORD_999",
"priority": "high"
}
}
}| Name | Type | Required | Description |
|---|---|---|---|
agent_id | string | Yes | ID of the agent that will make the call. |
contact_number | string | Yes | Number with country code, for example +91XXXXXXXXXX. |
contact_name | string | No | Recipient's name, used as context by the agent. |
contact_email | string | No | Email address for follow-up. |
contact_preferred_language | string | No | Language for this call only, for example "hindi". Falls back to the agent's configured language. |
scheduled_time | string | No | ISO 8601 time to place the call. Needs an explicit UTC offset and must be in the future. Defaults to about 15 seconds after the request. |
additional_info | object | No | Up to 25 key-value pairs of custom data for the agent. |
scheduled_time must end in Z or an explicit offset such as +05:30, for example 2026-07-15T18:30:00Z or 2026-07-15T18:30:00+05:30. A time with no offset, such as 2026-07-15T18:30:00, is rejected with 400, because otherwise it would be read in the server's local time zone and could land at a different real time depending on which server handled it.
call.cancel
Tries to cancel a call that is still scheduled.
{
"action": "call.cancel",
"data": {
"call_id": "call_xyz_789"
}
}| Name | Type | Required | Description |
|---|---|---|---|
data.call_id | string | Yes | The call_id of the scheduled call to cancel. |
call.delete
Permanently deletes a completed call and erases the customer's personal data (transcript, contact details, recording metadata). Only works on calls with a recorded engagement, meaning calls that connected. See Deleting Calls.
{
"action": "call.delete",
"data": {
"call_id": "call_xyz_789"
}
}| Name | Type | Required | Description |
|---|---|---|---|
data.call_id | string | Yes | The call_id of the completed call to delete. |
Signature verification (optional)
When Signature Verification is switched on for your inbound webhook, requests must be signed with HMAC-SHA256 using your Inbound Signing Secret, and Xebit checks every one.
Headers
| Header | Description |
|---|---|
X-Inbound-Timestamp | Current Unix timestamp. |
X-Inbound-Signature | The HMAC-SHA256 signature as a hex string. |
How the signature is checked
- The
X-Inbound-TimestampandX-Inbound-Signatureheaders are read from the request. - The signature is recomputed as the hex HMAC-SHA256 of
timestamp.rawBody, keyed with the Inbound Signing Secret. - The two values are compared.
- On a mismatch the request is rejected with
401 Unauthorized.
The samples below sign a request on the sending side. Send exactly the bytes you signed.
# Sign the body with your Inbound Signing Secret, then send it
SECRET="YOUR_INBOUND_SIGNING_SECRET"
TIMESTAMP="$(date +%s)"
PAYLOAD='{"action":"call.create","data":{"agent_id":"agent_abc_123","contact_number":"+919876543210"}}'
# Hex HMAC-SHA256 of "timestamp.rawBody"
SIGNATURE=$(printf '%s.%s' "$TIMESTAMP" "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')
curl -X POST "https://api.voice.xebit.ai/v1/hooks/YOUR_SECRET_TOKEN" \
-H "Content-Type: application/json" \
-H "X-Inbound-Timestamp: $TIMESTAMP" \
-H "X-Inbound-Signature: $SIGNATURE" \
--data-binary "$PAYLOAD"import hashlib
import hmac
import json
import os
import time
import requests
URL = "https://api.voice.xebit.ai/v1/hooks/YOUR_SECRET_TOKEN"
secret = os.environ["XEBIT_INBOUND_SIGNING_SECRET"]
raw_body = json.dumps({"action": "call.create", "data": {"agent_id": "agent_abc_123", "contact_number": "+919876543210"}})
timestamp = str(int(time.time()))
signature = hmac.new(secret.encode(), f"{timestamp}.{raw_body}".encode(), hashlib.sha256).hexdigest()
response = requests.post(URL, data=raw_body, headers={
"Content-Type": "application/json",
"X-Inbound-Timestamp": timestamp,
"X-Inbound-Signature": signature,
})
print(response.status_code, response.json())const crypto = require("crypto");
const URL = "https://api.voice.xebit.ai/v1/hooks/YOUR_SECRET_TOKEN";
const secret = process.env.XEBIT_INBOUND_SIGNING_SECRET;
const rawBody = JSON.stringify({ action: "call.create", data: { agent_id: "agent_abc_123", contact_number: "+919876543210" } });
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
const response = await fetch(URL, {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Inbound-Timestamp": timestamp,
"X-Inbound-Signature": signature,
},
body: rawBody, // send exactly the bytes you signed
});
console.log(response.status, await response.json());# Sign the body with your Inbound Signing Secret, then send it
SECRET="YOUR_INBOUND_SIGNING_SECRET"
TIMESTAMP="$(date +%s)"
PAYLOAD='{"action":"call.create","data":{"agent_id":"agent_abc_123","contact_number":"+919876543210"}}'
# Hex HMAC-SHA256 of "timestamp.rawBody"
SIGNATURE=$(printf '%s.%s' "$TIMESTAMP" "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')
curl -X POST "https://<your-xebit-voicekit-host>/v1/hooks/YOUR_SECRET_TOKEN" \
-H "Content-Type: application/json" \
-H "X-Inbound-Timestamp: $TIMESTAMP" \
-H "X-Inbound-Signature: $SIGNATURE" \
--data-binary "$PAYLOAD"import hashlib
import hmac
import json
import os
import time
import requests
URL = "https://<your-xebit-voicekit-host>/v1/hooks/YOUR_SECRET_TOKEN"
secret = os.environ["XEBIT_INBOUND_SIGNING_SECRET"]
raw_body = json.dumps({"action": "call.create", "data": {"agent_id": "agent_abc_123", "contact_number": "+919876543210"}})
timestamp = str(int(time.time()))
signature = hmac.new(secret.encode(), f"{timestamp}.{raw_body}".encode(), hashlib.sha256).hexdigest()
response = requests.post(URL, data=raw_body, headers={
"Content-Type": "application/json",
"X-Inbound-Timestamp": timestamp,
"X-Inbound-Signature": signature,
})
print(response.status_code, response.json())const crypto = require("crypto");
const URL = "https://<your-xebit-voicekit-host>/v1/hooks/YOUR_SECRET_TOKEN";
const secret = process.env.XEBIT_INBOUND_SIGNING_SECRET;
const rawBody = JSON.stringify({ action: "call.create", data: { agent_id: "agent_abc_123", contact_number: "+919876543210" } });
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
const response = await fetch(URL, {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Inbound-Timestamp": timestamp,
"X-Inbound-Signature": signature,
},
body: rawBody, // send exactly the bytes you signed
});
console.log(response.status, await response.json());Never act on an inbound payload that fails signature validation.
Rotating the token
Rotating the secret token invalidates the old one at once; requests that still use it get 401 Unauthorized.
Rotate when a token has been exposed, or as part of a routine security review:
- Open the Xebit VoiceCloud dashboard → Integrations → Inbound Webhooksthe Xebit VoiceKit admin console → Integrations → Inbound Webhooks.
- Choose Regenerate Token.
- Update every connected system with the new URL straight away.
Line up the change in every connected system before you rotate. Anything still using the old token stops working the moment you regenerate.
Response codes
| Code | Meaning |
|---|---|
200 OK | call.cancel or call.delete succeeded. |
201 Created | call.create was queued. |
400 Bad Request | Validation error, for example an invalid phone number format. |
401 Unauthorized | Invalid token or failed signature. |
402 Payment Required | Not enough balance to perform the action. |
404 Not Found | call.cancel or call.delete: no matching call. |
409 Conflict | call.cancel: the call exists but can no longer be cancelled. |
429 Too Many Requests | The daily request quota has been used up. See Quotas. |
On Xebit VoiceCloud, 402 means your prepaid minute balance cannot cover the action.
On Xebit VoiceKit, call volume is covered by your flat licence, so whether 402 can occur depends on how your deployment is configured.