Jump to

Webhooks

Webhooks let you receive HTTP POST callbacks for phone number events. Configure a webhook URL directly on your phone number via PATCH /numbers/{phone_number_id} — no separate webhook CRUD is needed.

Event types

Event	Description
`incoming_call`	An inbound call was received on the phone number

Configuring webhooks PATCH

PATCH /numbers/{phone_number_id}

To enable webhooks, set incoming_call_action to "webhook" and provide an incoming_call_webhook_url on the phone number.

Request body

Field	Type	Description
`incoming_call_action`	string	Set to `"webhook"` to enable webhook callbacks for incoming calls
`incoming_call_webhook_url`	string	HTTPS endpoint to receive webhook POSTs

Request example

JSON

Code examples

Incoming call webhook

When an incoming_call event fires, Inkbox sends a signed POST request to the configured webhook URL. Your endpoint must respond with an action instructing Inkbox how to handle the call:

JSON

Response fields

Field	Type	Description
`action`	string	`"answer"` to accept the call, `"reject"` to decline
`client_websocket_url`	string	WebSocket URL that Inkbox connects to for the call. Can carry text or audio, depending on how the connection is configured. Falls back to the phone number's configured `client_websocket_url` if omitted.

Verifying webhook signatures

Inkbox signs every webhook payload with your organization's signing key. Create or rotate your key via the Signing Keys API. Three headers are included with each request:

Header	Description
`X-Inkbox-Request-ID`	Unique request identifier
`X-Inkbox-Timestamp`	Unix timestamp (seconds)
`X-Inkbox-Signature`	`sha256=<hex_digest>` HMAC-SHA256 signature

The signature input is: {request_id}.{timestamp}.{raw_body}

To verify a webhook:

Check the timestamp is within 300 seconds of the current time
Reconstruct the signed message: {X-Inkbox-Request-ID}.{X-Inkbox-Timestamp}.{raw_body}
Compute the HMAC-SHA256 using your organization's signing key
Compare the hex digest with the sha256=... value from the header

Python verification example

Python

Disabling webhooks

To stop receiving webhooks, update the phone number to remove the webhook URL and change the action:

JSON