Cancelling Calls
Stop a queued call before it is dialled, through the REST API or an inbound webhook.
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.
You can stop a call that has not been dialled yet. This avoids a pointless call when the person has already done what the call was meant to prompt, such as paying an invoice.
Cancel with the REST API
/v1/calls/{call_id}/cancelRequires the calls:cancel scope. Best for programmatic control from your backend.
curl -s -X POST "https://api.voice.xebit.ai/v1/calls/call_abc_123/cancel" \
-H "x-api-key: $XEBIT_API_KEY"import os
import requests
BASE_URL = "https://api.voice.xebit.ai/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
call_id = "call_abc_123"
response = requests.post(
f"{BASE_URL}/calls/{call_id}/cancel",
headers={"x-api-key": API_KEY}
)
print(response.status_code, response.json())const BASE_URL = "https://api.voice.xebit.ai/v1";
const API_KEY = process.env.XEBIT_API_KEY;
const callId = "call_abc_123";
const response = await fetch(`${BASE_URL}/calls/${callId}/cancel`, {
method: "POST",
headers: { "x-api-key": API_KEY }
});
console.log(response.status, await response.json());curl -s -X POST "https://<your-xebit-voicekit-host>/v1/calls/call_abc_123/cancel" \
-H "x-api-key: $XEBIT_API_KEY"import os
import requests
BASE_URL = "https://<your-xebit-voicekit-host>/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
call_id = "call_abc_123"
response = requests.post(
f"{BASE_URL}/calls/{call_id}/cancel",
headers={"x-api-key": API_KEY}
)
print(response.status_code, response.json())const BASE_URL = "https://<your-xebit-voicekit-host>/v1";
const API_KEY = process.env.XEBIT_API_KEY;
const callId = "call_abc_123";
const response = await fetch(`${BASE_URL}/calls/${callId}/cancel`, {
method: "POST",
headers: { "x-api-key": API_KEY }
});
console.log(response.status, await response.json());Sample response:
{
"data": {
"call_id": "e95bd2f6-69e3-4918-856a-65f1197613de",
"status": "cancelled",
"cancelled_at": "2026-07-07T13:15:27.570Z"
}
}Cancel with an inbound webhook
/v1/hooks/{YOUR_SECRET_TOKEN}Useful when a CRM or billing system should cancel the call the moment something changes. Send the call.cancel action.
curl -s -X POST "https://api.voice.xebit.ai/v1/hooks/YOUR_SECRET_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"action": "call.cancel",
"data": {
"call_id": "call_abc_789"
}
}'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.cancel",
"data": {
"call_id": "call_abc_789"
}
}
)
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.cancel",
data: {
call_id: "call_abc_789"
}
})
});
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.cancel",
"data": {
"call_id": "call_abc_789"
}
}'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.cancel",
"data": {
"call_id": "call_abc_789"
}
}
)
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.cancel",
data: {
call_id: "call_abc_789"
}
})
});
console.log(response.status, await response.json());| Name | Type | Required | Description |
|---|---|---|---|
action | string | Yes | Must be "call.cancel". |
data.call_id | string | Yes | The call_id of the scheduled call to cancel. |
Important constraints
A call moves through these states in order: queued → initiated → ringing → in_progress.
- Timing: only a call in the
queuedstate can be cancelled. - Active calls: once a call reaches
initiated,ringingorin_progress, these endpoints cannot stop it. The API answers409 Conflict. - Idempotency: sending cancel again for the same
call_idis safe and does not produce an error.
On Xebit VoiceCloud, a call usually leaves the queue about 15 seconds after it was created when no scheduled_time was set, so cancel immediate calls promptly.
On Xebit VoiceKit, how quickly a queued call is dialled depends on your deployment's capacity and pacing configuration, so cancel immediate calls promptly.