Jump to

Webhooks

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

Event types

Event	Description
`phone.incoming_call`	An inbound call hit a phone number configured for webhook call handling
`text.received`	An inbound SMS or MMS arrived on a phone number with text webhooks enabled

Configuring webhooks PATCH

PATCH /numbers/{phone_number_id}

To enable incoming-call webhooks, set incoming_call_action to "webhook" and provide an incoming_call_webhook_url on the phone number. To enable inbound text webhooks, set incoming_text_webhook_url.

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 incoming-call webhook POSTs
`incoming_text_webhook_url`	string	HTTPS endpoint to receive inbound SMS/MMS webhook POSTs

Request example

JSON

Code examples

Incoming call webhook

When a phone.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.

Incoming text webhook

When a text.received event fires, Inkbox sends a signed POST request to the configured incoming_text_webhook_url. This webhook is fire-and-forget: any response body is ignored.

Payload shape

The payload includes:

event_type: "text.received"
timestamp
data.text_message with the stored inbound SMS/MMS record

Verifying webhook signatures

Inkbox signs every webhook payload with your organization's signing key. Create or rotate your key via the Signing Keys guide. 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