Webhook Subscriptions

A webhook subscription names one owner — a mailbox, a phone number, or an agent identity — one HTTPS destination URL, and a non-empty list of event types from the webhook catalog. When a matching event fires, Inkbox POSTs the payload to the subscription's URL.

Mail and text subscriptions are owned by the mailbox or phone number. iMessage and call-lifecycle subscriptions are owned by the agent identity, because that traffic can ride shared lines rather than a number you own — see iMessage webhooks and Phone webhooks.

You can attach up to 20 active subscriptions per owner (mailbox, phone number, or agent identity). Each URL receives its own POST per event, independently — one slow receiver doesn't block delivery to the others. A 21st POST /webhooks/subscriptions on the same owner returns 409; delete an existing subscription first.

phone.incoming_call is not subscribable. That event is a synchronous control-plane callback — the response body decides whether Inkbox answers the call — so it can't fan out. Configure it via the incoming_call_webhook_url field on the phone number resource instead.

Unclaimed agent-scoped API keys are rejected.

POST /webhooks/subscriptions

Create a new subscription on a mailbox, a phone number, or an agent identity.

Request body

Request example

JSON

Create subscription response

A successful create returns 201 with the created subscription: the shared Subscription object plus a one-time signing_key field that no other endpoint returns.

JSON

Signing keys are per owning identity, so the secret returned here belongs to this subscription's owning identity (owner_identity_id) and verifies every webhook for that identity. All other fields are the shared Subscription object.

Validation errors

Code examples

cURL

cURL

JavaScript

Python

GET /webhooks/subscriptions

List active subscriptions visible to the caller, newest first. Returns an object with a subscriptions array — not a bare array.

Query parameters

Filters AND-combine. Foreign-organization rows are filtered out, so they never appear in results.

Response (200)

JSON

Error responses

Code examples

cURL

cURL

JavaScript

Python

GET /webhooks/subscriptions/{sub_id}

Path parameters

Response (200)

Returns the subscription object. See Subscription object.

Error responses

Code examples

cURL

cURL

JavaScript

Python

PATCH /webhooks/subscriptions/{sub_id}

Update a subscription's destination URL and/or event list in place. The owner FKs are immutable — to move a subscription to a different mailbox, phone number, or agent identity, delete it and create a new one.

Path parameters

Request body

Supplying any subset of these is fine. Supplying none no-ops.

Request example

JSON

Response (200)

Returns the updated subscription object. See Subscription object.

Validation errors

Code examples

cURL

cURL

JavaScript

Python

DELETE /webhooks/subscriptions/{sub_id}

Remove a subscription. Inkbox stops delivering events to the URL immediately. Subsequent reads on the same sub_id return 404.

Path parameters

Response (204)

No body.

Error responses

Code examples

cURL

cURL

JavaScript

Python

event_types is a non-empty list drawn from the same catalog the webhook payload pages document:

An agent identity can own subscriptions on either identity channel, but a single subscription carries one channel — call.ended and imessage.* never share a row.

phone.incoming_call is not in this list. It is managed via incoming_call_webhook_url on the phone number resource.

Set context_config to opt a subscription into conversation context. On received events — message.received, text.received, and imessage.received — the delivered payload then carries a data.context object with recent history, so your handler can act with context without a follow-up API call. Delivery-status events never carry context.

context_config holds up to three independent class keys:

Omit a class to leave it unconfigured. Each configured class picks one of two modes:

The object is validated strictly: an unknown class key, an unknown mode, a count/hours out of range, or any unexpected field returns 422. An all-empty object is stored as no context (null).

JSON

On update, context_config is tri-state: an object replaces the stored config, null clears it, and omitting the field leaves it unchanged.

The delivered data.context block — its scopes, per-class items, transcript abridgment, skip reasons, and the 256 KB size cap — is documented alongside the payloads on the Mail, Phone, and iMessage webhook pages.

• Webhooks guide — payload verification, typed receiver examples
• Mail webhooks reference — message.* payload shapes
• Phone webhooks reference — text.*, call.ended, and phone.incoming_call payload shapes
• iMessage webhooks reference — imessage.* payload shapes
• Signing keys — per-identity keys used to verify webhook bodies