Webhook Subscriptions

A webhook subscription names one owner — a mailbox or a phone number — 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.

You can attach up to 20 active subscriptions per owner (mailbox or phone number). 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 or a phone number.

Request body

Request example

JSON

Response (201)

Returns the new subscription object. See 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 or phone number, delete it and create a new one.

Path parameters

Request body

Supplying both fields is fine. Supplying neither 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:

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

• Webhooks guide — payload verification, typed receiver examples
• Mail webhooks reference — message.* payload shapes
• Phone webhooks reference — text.* and phone.incoming_call payload shapes
• Signing keys — rotate the org-level HMAC key used to sign webhook bodies