Webhook Subscriptions

A webhook subscription belongs to one agent identity, names one HTTPS destination URL, and selects a non-empty list of notification types from the webhook catalog. When a matching event fires, Inkbox POSTs the payload to the subscription’s URL. You can mix email, SMS/MMS, iMessage, call-lifecycle, Agent2Agent, and Slack events in one subscription. All 44 notification types are available even before their channels are enabled or attached. Selecting events does not provision resources, enable channels, change billing, or replay past events. Selected events begin arriving when their channel becomes active; disabling one channel preserves the subscription and its other selections. You can attach up to 60 active subscriptions per identity. Each URL receives its own POST per event, independently — one slow receiver doesn’t block delivery to the others. A request that would create a 61st active subscription on the same identity 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 the identity’s incoming-call action instead.

Auth

Caller	Visibility
Admin-scoped API key	Every subscription in the organization.
Human session via the Inkbox Console	Every subscription in the organization.
Claimed agent-scoped API key	Only subscriptions belonging to that agent’s identity.

Unclaimed agent-scoped API keys are rejected.

Create subscription

POST /webhooks/subscriptions

Create a subscription on an agent identity. You can configure several destination URLs, or combine event families at one URL.

Request body

Field	Type	Required	Description
`mailbox_id`	UUID	No	Deprecated compatibility selector. Resolves the mailbox to its owning identity; prefer `agent_identity_id`. Supply only one owner selector.
`phone_number_id`	UUID	No	Deprecated compatibility selector. Resolves the number to its owning identity; prefer `agent_identity_id`. Supply only one owner selector.
`agent_identity_id`	UUID	Yes, unless using a compatibility selector	Owning agent identity for every notification type.
`url`	string	Yes	HTTPS destination for delivered events.
`event_types`	array of strings	Yes	Non-empty, distinct list of known notification types. Any combination of the 44 types is allowed.
`context_config`	object \| null	No	Per-class conversation context included only in `message.received`, `text.received`, and `imessage.received` payloads. Other selected events ignore it.
`auth_token`	string	No	Optional bearer token for endpoints that require authentication. When set, every delivery for this subscription — live events and replays alike — carries `Authorization: Bearer <token>` alongside the signature headers. The stored token is returned on subscription reads as `auth_token`.

Request example

JSON

{
  "agent_identity_id": "5f2a7c9e-1b3d-4e6f-8a0c-2d4e6f8a0c1d",
  "url": "https://yourapp.example.com/webhooks/inkbox",
  "event_types": ["message.received", "text.received", "imessage.received", "call.ended", "a2a.task.created"]
}

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

{
  "id": "9e1b3f2d-c4a6-4f8e-91bf-71d2c2e4f0a1",
  "organization_id": "org_2abc123def456",
  "agent_identity_id": "5f2a7c9e-1b3d-4e6f-8a0c-2d4e6f8a0c1d",
  "phone_number_id": null,
  "mailbox_id": null,
  "owner_identity_id": "5f2a7c9e-1b3d-4e6f-8a0c-2d4e6f8a0c1d",
  "url": "https://yourapp.example.com/webhooks/inkbox",
  "event_types": ["message.received", "text.received", "imessage.received", "call.ended", "a2a.task.created"],
  "context_config": null,
  "auth_token": null,
  "has_auth_token": false,
  "status": "active",
  "signing_key": "7K9x2mP4qR8vT1wY3zA5bC6dE0fG...",
  "created_at": "2026-04-10T18:00:00Z",
  "updated_at": "2026-04-10T18:00:00Z"
}

Field	Type	Description
`signing_key`	string \| null	The owning identity’s webhook signing secret, returned once — only on the first subscription you create for an identity that had no key yet. `null` (or omitted) on every other create. Store it now; it cannot be retrieved again. See Signing keys.

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.

Reuse a mixed subscription

A create can reuse one existing mixed subscription at the exact same URL when its requested events belong to a single supported family. Use mailbox_id for email-only requests, phone_number_id for text-only requests, or agent_identity_id for iMessage-only, call-only, Agent2Agent-only, or Slack-only requests. Omit auth_token and context_config. Exactly one active subscription for that identity and exact URL must overlap the requested events, and it must already select events from more than one family. The 201 response returns that existing subscription’s ID. The request adds only missing events and preserves its settings and other events. Receiving that ID does not authorize an update or deletion without scope=identity. This does not merge subscriptions or make all creates idempotent. Ambiguous matches, an existing single-family subscription, multi-family requests, or requests that specify authentication or context still return 409 on overlap. Keep separately managed destinations separate unless they intentionally share a receiver.

Validation errors

Status	Reason
`422`	Body did not specify exactly one of `mailbox_id` / `phone_number_id` / `agent_identity_id`.
`422`	`event_types` was empty or contained duplicates.
`422`	An event type is unknown or is not a subscribable notification.
`422`	`phone.incoming_call` was included — managed via the identity’s incoming-call action instead.
`422`	`context_config` was malformed: an unknown class key, an unknown `mode`, `count` outside 1–50, `hours` outside 1–168, or an unexpected field (the object is validated strictly).
`422`	`auth_token` is not a valid token: it must be 8–4096 visible ASCII characters (no spaces, control characters, or non-ASCII text).
`403`	The owner belongs to a different organization than the caller.
`404`	The owner is not visible to the caller (does not exist, or hidden by access scope).
`409`	The selected mailbox or phone number is not assigned to an identity.
`409`	The selected resource is not assigned to an organization.
`409`	Another active subscription for this identity and exact URL already selects a requested event, unless the request qualifies to reuse a mixed subscription. Disjoint event selections may share a URL.

Code examples

curl -X POST "https://inkbox.ai/api/v1/webhooks/subscriptions" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_identity_id": "5f2a7c9e-1b3d-4e6f-8a0c-2d4e6f8a0c1d",
    "url": "https://yourapp.example.com/webhooks/inkbox",
    "event_types": ["message.received", "text.received", "imessage.received", "call.ended", "a2a.task.created"]
  }'

const response = await fetch(
  "https://inkbox.ai/api/v1/webhooks/subscriptions",
  {
      method: "POST",
      headers: {
          "X-API-Key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({
          agent_identity_id: "5f2a7c9e-1b3d-4e6f-8a0c-2d4e6f8a0c1d",
          url: "https://yourapp.example.com/webhooks/inkbox",
          event_types: ["message.received", "text.received", "imessage.received", "call.ended", "a2a.task.created"],
      }),
  }
);
const subscription = await response.json();

import requests

response = requests.post(
    "https://inkbox.ai/api/v1/webhooks/subscriptions",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "agent_identity_id": "5f2a7c9e-1b3d-4e6f-8a0c-2d4e6f8a0c1d",
        "url": "https://yourapp.example.com/webhooks/inkbox",
        "event_types": ["message.received", "text.received", "imessage.received", "call.ended", "a2a.task.created"],
    },
)
subscription = response.json()

List subscriptions

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

Parameter	Type	Description
`mailbox_id`	UUID	Deprecated compatibility filter: returns mail-only subscriptions for the owning identity. The three owner selectors are mutually exclusive.
`phone_number_id`	UUID	Deprecated compatibility filter: returns text-only subscriptions for the owning identity. The three owner selectors are mutually exclusive.
`agent_identity_id`	UUID	Filter by owning identity. Add `scope=identity` to include all notification families and mixed subscriptions. Without it, the historical identity-event view is preserved.
`scope`	`identity`	Opt in to the complete identity-owned subscription list instead of a legacy selector’s event-family view. SDK identity-filtered lists preserve the legacy view by default; pass `scope="identity"` explicitly to include mixed subscriptions.
`url`	string	Filter by exact destination URL.
`event_type`	string	Filter by event type. `phone.incoming_call` is rejected — that event isn’t stored as a subscription.
`limit`	integer	Maximum rows to return (1–200). Omit to return all visible subscriptions.
`offset`	integer	Rows to skip (0–10,000). Defaults to `0`.

Identity-wide scope requires supports_identity_subscriptions: true in GET /webhooks/catalog. SDK/CLI version 0.7.8 or later checks this capability before an explicit identity-wide list. For a complete identity list, use GET /webhooks/subscriptions?agent_identity_id=IDENTITY_ID&scope=identity. Legacy filtered lists exclude mixed subscriptions so older integrations cannot accidentally replace another event family’s configuration. An unfiltered list still returns all visible subscriptions. Updates and deletion of a mixed subscription require an explicit scope=identity query parameter. Without it, the server returns 409 without changing the subscription. SDK/CLI 0.7.8 exposes this opt-in but does not add it automatically; upgrading an existing caller preserves its defaults. Filters AND-combine. Foreign-organization rows are filtered out, so they never appear in results.

Response (200)

JSON

{
  "subscriptions": [
      {
          "id": "9e1b3f2d-c4a6-4f8e-91bf-71d2c2e4f0a1",
          "organization_id": "org_2abc123def456",
          "agent_identity_id": "5f2a7c9e-1b3d-4e6f-8a0c-2d4e6f8a0c1d",
          "phone_number_id": null,
          "mailbox_id": null,
          "owner_identity_id": "5f2a7c9e-1b3d-4e6f-8a0c-2d4e6f8a0c1d",
          "url": "https://yourapp.example.com/webhooks/inkbox",
          "event_types": ["message.received", "text.received", "imessage.received", "call.ended", "a2a.task.created"],
          "context_config": null,
          "auth_token": null,
          "has_auth_token": false,
          "status": "active",
          "created_at": "2026-04-10T18:00:00Z",
          "updated_at": "2026-04-10T18:00:00Z"
      }
  ]
}

Error responses

Status	Reason
`422`	More than one owner filter supplied.
`422`	`event_type=phone.incoming_call`.

Code examples

curl -X GET "https://inkbox.ai/api/v1/webhooks/subscriptions?agent_identity_id=5f2a7c9e-1b3d-4e6f-8a0c-2d4e6f8a0c1d&scope=identity" \
  -H "X-API-Key: YOUR_API_KEY"

const url = new URL("https://inkbox.ai/api/v1/webhooks/subscriptions");
url.searchParams.set("agent_identity_id", "5f2a7c9e-1b3d-4e6f-8a0c-2d4e6f8a0c1d");
url.searchParams.set("scope", "identity");
const response = await fetch(url, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { subscriptions } = await response.json();

import requests

response = requests.get(
    "https://inkbox.ai/api/v1/webhooks/subscriptions",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"agent_identity_id": "5f2a7c9e-1b3d-4e6f-8a0c-2d4e6f8a0c1d", "scope": "identity"},
)
subscriptions = response.json()["subscriptions"]

Get subscription

GET /webhooks/subscriptions/{sub_id}

Path parameters

Parameter	Type	Description
`sub_id`	UUID	Unique subscription identifier.

Response (200)

Returns the subscription object. See Subscription object.

Error responses

Status	Reason
`404`	Subscription does not exist or is not visible to the caller. Foreign-organization subscriptions return `404`.

Code examples

curl -X GET "https://inkbox.ai/api/v1/webhooks/subscriptions/SUB_ID" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch(
  `https://inkbox.ai/api/v1/webhooks/subscriptions/${subId}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const subscription = await response.json();

import requests

response = requests.get(
    f"https://inkbox.ai/api/v1/webhooks/subscriptions/{sub_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
subscription = response.json()

Update subscription

PATCH /webhooks/subscriptions/{sub_id}?scope=identity

Update a subscription’s destination URL and/or event list in place. The identity owner is immutable. To move a subscription to another identity, delete it and create a new one. Changing a URL, token, or event list affects the whole subscription, including every selected channel.

Path parameters

Parameter	Type	Description
`sub_id`	UUID	Unique subscription identifier.

Request body

Field	Type	Required	Description
`url`	string	No	New HTTPS destination. Omit to leave unchanged.
`event_types`	array of strings	No	New non-empty, distinct list of event types. Any mix of known notification types is allowed. This replaces the complete list; omit it to keep all existing selections.
`context_config`	object \| null	No	Tri-state: send an object to replace the stored conversation-context config, `null` to clear it, or omit the field to leave it unchanged. Other event types ignore the configured context.
`auth_token`	string \| null	No	Tri-state: send a string to replace the stored delivery bearer token, `null` to clear it, or omit the field to leave it unchanged. See Authenticating to your endpoint.

Supply only the fields you want to change. If multiple clients update the same field, the last successful update wins.

Request example

JSON

{
  "event_types": ["message.received", "message.delivered", "message.bounced"]
}

Response (200)

Returns the updated subscription object. See Subscription object.

Validation errors

Status	Reason
`422`	`event_types` was empty or contained duplicates.
`422`	An event type is unknown or not subscribable.
`422`	`phone.incoming_call` was included.
`422`	`auth_token` is not a valid token: it must be 8–4096 visible ASCII characters (no spaces, control characters, or non-ASCII text).
`404`	Subscription does not exist or is not visible to the caller.
`409`	The effective event types overlap another active subscription on this identity and URL.
`409`	The subscription mixes event families and the request omitted `scope=identity`. Review all selected events before opting in.
`409`	The subscription owner is unavailable or changed while the request ran. Refresh the subscription and its owner before retrying.

Code examples

curl -X PATCH "https://inkbox.ai/api/v1/webhooks/subscriptions/SUB_ID?scope=identity" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_types": ["message.received", "message.delivered", "message.bounced"]}'

const response = await fetch(
  `https://inkbox.ai/api/v1/webhooks/subscriptions/${subId}?scope=identity`,
  {
      method: "PATCH",
      headers: {
          "X-API-Key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({
          event_types: ["message.received", "message.delivered", "message.bounced"],
      }),
  }
);
const subscription = await response.json();

import requests

response = requests.patch(
    f"https://inkbox.ai/api/v1/webhooks/subscriptions/{sub_id}?scope=identity",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"event_types": ["message.received", "message.delivered", "message.bounced"]},
)
subscription = response.json()

Delete subscription

DELETE /webhooks/subscriptions/{sub_id}?scope=identity

Remove the complete subscription, stopping all its selected notifications. To stop only one event family, update the event list instead. Subsequent reads on the same sub_id return 404.

Path parameters

Parameter	Type	Description
`sub_id`	UUID	Unique subscription identifier.

Response (204)

No body.

Error responses

Status	Reason
`404`	Subscription does not exist or is not visible to the caller.
`409`	The subscription mixes event families and the request omitted `scope=identity`. Review all selected events before opting in.
`409`	The subscription owner is unavailable or changed while the request ran. Refresh the subscription and its owner before retrying.

Code examples

curl -X DELETE "https://inkbox.ai/api/v1/webhooks/subscriptions/SUB_ID?scope=identity" \
  -H "X-API-Key: YOUR_API_KEY"

await fetch(
  `https://inkbox.ai/api/v1/webhooks/subscriptions/${subId}?scope=identity`,
  {
      method: "DELETE",
      headers: { "X-API-Key": "YOUR_API_KEY" },
  }
);

import requests

requests.delete(
    f"https://inkbox.ai/api/v1/webhooks/subscriptions/{sub_id}?scope=identity",
    headers={"X-API-Key": "YOUR_API_KEY"},
)

Subscription object

Field	Type	Description
`id`	UUID	Unique subscription identifier.
`organization_id`	string	Owning organization (e.g. `"org_2abc123def456"`). Server-derived from the owner — never read from the request body.
`mailbox_id`	UUID \| null	Deprecated compatibility field. `null` for new, updated, or migrated subscriptions. Older rows may retain the original channel owner.
`phone_number_id`	UUID \| null	Deprecated compatibility field. `null` for new, updated, or migrated subscriptions. Older rows may retain the original channel owner.
`agent_identity_id`	UUID \| null	Owning identity for every selected event family. Older subscriptions may return `null` until updated or migrated; use `owner_identity_id` to resolve ownership during this transition.
`owner_identity_id`	string \| null	Resolved identity owner, equal to `agent_identity_id` for identity-owned subscriptions. Retained for compatibility.
`url`	string	HTTPS destination for delivered events.
`event_types`	array of strings	Event types this subscription delivers. Values may span any notification family.
`context_config`	object \| null	Per-class conversation-context configuration, echoing what you set, or `null` when the subscription requests no context. Applied only on received email, text and iMessage events.
`auth_token`	string \| null	The stored delivery bearer auth token; `null` when none is set.
`has_auth_token`	boolean	Whether a delivery auth token is configured on this subscription.
`status`	string	Always `"active"` on returned rows. Deleted rows are not returned by any endpoint.
`created_at`	string	ISO 8601 timestamp the subscription was created.
`updated_at`	string	ISO 8601 timestamp the subscription was last updated.

Event types

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

Channel	Allowed values
Mail	`message.received`, `message.sent`, `message.forwarded`, `message.delivered`, `message.bounced`, `message.failed`
Phone text	`text.received`, `text.sent`, `text.delivered`, `text.delivery_failed`, `text.delivery_unconfirmed`
iMessage	`imessage.received`, `imessage.reaction_received`, `imessage.sent`, `imessage.delivered`, `imessage.delivery_failed`
Slack	The 23 Slack event types
Call lifecycle	`call.ended`
Agent2Agent	`a2a.task.created`, `a2a.task.message`, `a2a.task.canceled`, `a2a.sent_task.updated`

All event types above belong to the agent identity and may share one subscription. 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. Configure it through the identity’s incoming-call action.

Conversation context (`context_config`)

Set context_config to request conversation context on received notifications. A mixed subscription may store this configuration; other event types ignore it. 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:

Class	What it includes
`email`	Recent emails: the triggering thread on mail events, or mail exchanged with the matched contact on text/call events.
`texts`	Recent SMS and iMessage, merged into one chronological list.
`calls`	Recent calls, each with its transcript.

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

Mode	Field	Meaning
`count`	`count` (1–50)	The last N items of that class.
`window`	`hours` (1–168)	Everything from the last H hours, capped at the 50 newest items.

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

{
  "agent_identity_id": "5f2a7c9e-1b3d-4e6f-8a0c-2d4e6f8a0c1d",
  "url": "https://yourapp.example.com/webhooks/inkbox",
  "event_types": ["message.received"],
  "context_config": {
      "email": {"mode": "count", "count": 10},
      "texts": {"mode": "window", "hours": 24},
      "calls": {"mode": "count", "count": 2}
  }
}

On update, context_config is tri-state: an object replaces the stored config, null clears it, and omitting the field leaves it unchanged. Other selected event types, including Slack events, do not gain context. 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
Slack webhooks reference — Slack event selection and payloads

​Auth

​Create subscription

​Request body

​Request example

​Create subscription response

​Reuse a mixed subscription

​Validation errors

​Code examples

​List subscriptions

​Query parameters

​Response (200)

​Error responses

​Code examples

​Get subscription

​Path parameters

​Response (200)

​Error responses

​Code examples

​Update subscription

​Path parameters

​Request body

​Request example

​Response (200)

​Validation errors

​Code examples

​Delete subscription

​Path parameters

​Response (204)

​Error responses

​Code examples

​Subscription object

​Event types

​Conversation context (context_config)

​Related

Auth

Create subscription

Request body

Request example

Create subscription response

Reuse a mixed subscription

Validation errors

Code examples

List subscriptions

Query parameters

Response (200)

Error responses

Code examples

Get subscription

Path parameters

Response (200)

Error responses

Code examples

Update subscription

Path parameters

Request body

Request example

Response (200)

Validation errors

Code examples

Delete subscription

Path parameters

Response (204)

Error responses

Code examples

Subscription object

Event types

Conversation context (`context_config`)

Related