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

POST/v1/calls/{call_id}/cancel

Requires 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"
curl -s -X POST "https://<your-xebit-voicekit-host>/v1/calls/call_abc_123/cancel" \
  -H "x-api-key: $XEBIT_API_KEY"

Sample response:

JSON
{
  "data": {
    "call_id": "e95bd2f6-69e3-4918-856a-65f1197613de",
    "status": "cancelled",
    "cancelled_at": "2026-07-07T13:15:27.570Z"
  }
}

Cancel with an inbound webhook

POST/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"
    }
  }'
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"
    }
  }'
NameTypeRequiredDescription
actionstringYesMust be "call.cancel".
data.call_idstringYesThe 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 queued state can be cancelled.
  • Active calls: once a call reaches initiated, ringing or in_progress, these endpoints cannot stop it. The API answers 409 Conflict.
  • Idempotency: sending cancel again for the same call_id is 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.