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 webhookREST API
Best forNo-code tools, CRMs and automation platformsCustom applications and backend integrations
AuthenticationSecret token in the URLAPI key in a header

Endpoint configuration

Each inbound webhook has a secret token that identifies your organisation.

POST/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

  1. Find your secret token under the Xebit VoiceCloud dashboard → Integrations → Inbound Webhooksthe Xebit VoiceKit admin console → Integrations → Inbound Webhooks.
  2. Set action to call.create in the body.
  3. Add the contact details: agent_id and contact_number at minimum.
  4. POST the request to your inbound URL.
  5. A response with a call_id and status: scheduled confirms 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"
    }
  }'
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"
    }
  }'

Sample response:

JSON
{
  "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.

JSON
{
  "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"
    }
  }
}
NameTypeRequiredDescription
agent_idstringYesID of the agent that will make the call.
contact_numberstringYesNumber with country code, for example +91XXXXXXXXXX.
contact_namestringNoRecipient's name, used as context by the agent.
contact_emailstringNoEmail address for follow-up.
contact_preferred_languagestringNoLanguage for this call only, for example "hindi". Falls back to the agent's configured language.
scheduled_timestringNoISO 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_infoobjectNoUp 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.

JSON
{
  "action": "call.cancel",
  "data": {
    "call_id": "call_xyz_789"
  }
}
NameTypeRequiredDescription
data.call_idstringYesThe 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.

JSON
{
  "action": "call.delete",
  "data": {
    "call_id": "call_xyz_789"
  }
}
NameTypeRequiredDescription
data.call_idstringYesThe 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

HeaderDescription
X-Inbound-TimestampCurrent Unix timestamp.
X-Inbound-SignatureThe HMAC-SHA256 signature as a hex string.

How the signature is checked

  1. The X-Inbound-Timestamp and X-Inbound-Signature headers are read from the request.
  2. The signature is recomputed as the hex HMAC-SHA256 of timestamp.rawBody, keyed with the Inbound Signing Secret.
  3. The two values are compared.
  4. 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"
# 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"

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:

  1. Open the Xebit VoiceCloud dashboard → Integrations → Inbound Webhooksthe Xebit VoiceKit admin console → Integrations → Inbound Webhooks.
  2. Choose Regenerate Token.
  3. 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

CodeMeaning
200 OKcall.cancel or call.delete succeeded.
201 Createdcall.create was queued.
400 Bad RequestValidation error, for example an invalid phone number format.
401 UnauthorizedInvalid token or failed signature.
402 Payment RequiredNot enough balance to perform the action.
404 Not Foundcall.cancel or call.delete: no matching call.
409 Conflictcall.cancel: the call exists but can no longer be cancelled.
429 Too Many RequestsThe 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.