Webhooks

Webhooks let you receive HTTP POST callbacks for phone number events. Text events are delivered via the Webhook Subscriptions API — attach a subscription to the phone number with the subset of text.* events you want. The incoming-call event stays a per-number control-plane callback, configured on the phone number resource via incoming_call_webhook_url.

phone.incoming_call is not subscribable. Its handling is synchronous (your response decides whether Inkbox answers the call), so it can't fan out. Configure it via incoming_call_webhook_url on the phone number resource.

Inbound texts rejected by a contact-rule block or by default-block in whitelist mode are retained for admin review but do not emit text.received webhooks.

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.

Request body

Request example

JSON

Code examples

cURL

cURL

JavaScript

Python

Text events are delivered via the Webhook Subscriptions API. Two steps:

1. Have a phone number provisioned (see Phone numbers).
2. Create a subscription naming that phone number, the HTTPS destination URL, and the subset of text.* event types you want delivered.

You can attach up to 20 active subscriptions per number — split events across URLs, or fan one URL out across many numbers from many subscription rows. Creating a 21st returns 409; delete an existing one first.

Request example

JSON

Code examples

cURL

cURL

JavaScript

Python

See Webhook Subscriptions for the full CRUD surface, validation rules, and per-route error codes.

When a phone.incoming_call event fires, Inkbox sends a signed POST request to the configured webhook URL. The payload is flat — there is no {event_type, timestamp, data} envelope, and contacts + agent_identities sit at the top level alongside the call fields. Your endpoint must respond with an action instructing Inkbox how to handle the call.

Payload shape

JSON

Payload fields

contacts and agent_identities are always present on the wire and possibly empty. A peer that's both a contact and an internal agent appears once in each list.

Blocked calls do not dispatch webhooks — receivers only ever see calls that survived the inbound filter.

Response

Your endpoint must respond with an action instructing Inkbox how to handle the call. client_websocket_url is optional — omit it (or send null) to fall back to the phone number's configured client_websocket_url.

Override the fallback by supplying a per-call URL:

JSON

Use the phone number's configured fallback by omitting the field:

JSON

Response fields

All five text.* events share the standard {event_type, timestamp, data} envelope. data.text_message carries the stored text-message record. Two parallel peer-resolution lists ride alongside it:

All five events share the standard {event_type, timestamp, data} envelope. data.text_message carries the stored text-message record. For 1:1 traffic, the legacy remote_phone_number field stays populated. For outbound group lifecycle events, remote_phone_number is null; use data.recipient_phone_number for the recipient this event is about and data.text_message.recipients[] for the full per-recipient state.

Inbound — text.received

JSON

On inbound rows, sender_phone_number carries the remote sender (same value as remote_phone_number); recipients is null; data.recipient_phone_number is null.

The four outbound events share the same envelope and message shape as text.received. The headline value of these events is the delivery-state block. For 1:1 messages, delivery_status, error_code, error_detail, sent_at, delivered_at, and failed_at are mirrored on text_message; for group messages, delivery_status is a message-level rollup while per-recipient lifecycle details live in text_message.recipients[].

For groups, the top-level text_message.delivery_status is a rollup across recipients[] — the lowest lifecycle rank present, with "delivered" preferred at the terminal tier on mixed-outcome ties. Outbound events fan out one webhook per per-recipient transition, so a text.delivered event for one leg can fire while other legs are still "sent" — the rollup will still read "sent" until every leg reaches a terminal state. Treat recipients[].delivery_status as authoritative per-leg; use the rollup only for at-a-glance UI.

The four outbound events share the same envelope and message shape as text.received. The headline value is the delivery-state block — delivery_status, error_code, error_detail, sent_at, delivered_at, failed_at — which lets receivers act on outbound failures without a follow-up API call. On 1:1 outbound rows, those fields are hoisted out of recipients[0] for back-compat.

Example: text.delivery_failed on a 1:1 outbound send.

JSON

Example: outbound group text.delivered for one recipient.

JSON

The three other outbound events have the same shape with different terminal fields:

• text.sent — carrier accepted the message. delivery_status is "sent", sent_at is populated, delivered_at and failed_at are null.
• text.delivered — carrier confirmed handset delivery. delivery_status is "delivered", both sent_at and delivered_at are populated.
• text.delivery_unconfirmed — carrier could not confirm delivery within its reporting window. delivery_status is "delivery_unconfirmed", sent_at and failed_at are populated, delivered_at is null.

Outbound group lifecycle (group MMS)

When you send a group MMS (2+ recipients), each lifecycle event fires once per recipient, with data.recipient_phone_number identifying which leg the event is about. The text_message row carries remote_phone_number: null (no single remote party) and a top-level delivery_status rollup; legacy top-level timestamp/error fields stay null, and per-leg state lives in recipients[].

Example: text.delivered for one leg of a 3-recipient group send.

JSON

Receivers should detect group outbound by text_message.direction === "outbound" && text_message.remote_phone_number === null, then read data.recipient_phone_number to identify the leg and find the matching entry in text_message.recipients[] for that leg's delivery state.

Per-recipient × per-subscription fan-out

A 3-recipient group send with 2 active text subscriptions produces 6 POSTs per lifecycle stage — one per recipient leg, per subscription. Each POST carries the full group state in text_message.recipients[] plus the leg-identifying data.recipient_phone_number. Per-URL POSTs are independent: a slow receiver doesn't block delivery to the others. See Phone texts for the API surface around sending into a conversation_id or addressing a group send.

text_message field reference

recipients[i] shape

Inbound-call payloads carry top-level contacts and agent_identities. Text payloads carry data.contacts and data.agent_identities. Both are lists — always present and possibly empty — never null.

• Field shapes: contacts are { "id": "<uuid>", "name": "<preferred name>" }; agent identities are { "id": "<uuid>", "agent_handle": "<handle>", "display_name": "<name or null>" }.
• Scope: restricted to the identity that owns the receiving phone number. Contacts not visible to that identity are absent; internal agents are resolved against the per-identity identity_access table plus self-visibility.
• Inbound calls: match key is top-level remote_phone_number.
• Inbound texts: match key is data.text_message.remote_phone_number, also available as data.text_message.sender_phone_number.
• Outbound 1:1 text lifecycle events: match key is data.text_message.remote_phone_number; data.recipient_phone_number is null.
• Outbound group text lifecycle events: match key is data.recipient_phone_number, the recipient this lifecycle event is about. Use data.text_message.recipients[] to inspect every recipient in the conversation send.
• Tiebreak (contacts): if multiple visible contacts share the same phone, the oldest by created_at wins. Receivers needing disambiguation can call GET /contacts/lookup.
• Hydration: feed contacts[i].id into GET /api/v1/contacts/{contact_id}. For identities the endpoint is keyed by handle, not UUID: feed agent_identities[i].agent_handle into GET /api/v1/identities/{agent_handle}.

Both lists are always present on the wire. Treat empty lists as "no matches," never as errors.

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:

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

To verify a webhook:

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

Python verification example

Python

To stop receiving text webhooks at a URL, delete the subscription that owns it. Delivery stops immediately.

To stop receiving incoming-call webhooks, update the phone number to clear the URL and switch the action:

JSON

cURL

cURL

JavaScript

Python