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, call-lifecycle, and Agent2Agent subscriptions are owned by the agent identity, which stays the stable owner across channels — see iMessage webhooks, Phone webhooks, and Agent-to-Agent.

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 any identity channel, but a single subscription carries one channel. Separate identity subscriptions may use the same URL when their event lists are disjoint; requesting the same event on two active rows at that URL returns 409.

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 mail, text, or iMessage subscription into conversation context. Agent2Agent subscriptions do not support this field. 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 for supported channels: an object replaces the stored config, null clears it, and omitting the field leaves it unchanged. A non-null object is rejected when the subscription's effective event family is Agent2Agent.

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