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 A2A 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.

---

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

Request body

Request example

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.

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

---

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)

Error responses

Code examples

---

Path parameters

Response (200)

Returns the subscription object. See Subscription object.

Error responses

Code examples

---

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

Response (200)

Returns the updated subscription object. See Subscription object.

Validation errors

Code examples

---

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

---

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).

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