Webhooks

Register a webhook

Register a webhook endpoint. `url` must be HTTPS and `event_types` must list at least one event type; `inbox_ids` (max 10) optionally scopes the endpoint to specific inboxes (omit for all of the tenant's inboxes). Supply a `client_id` for idempotency — repeating a create with the same `client_id` returns the existing webhook (`200`). The response includes the endpoint's **signing secret** (`whsec_…`), returned **only** here — store it now to verify deliveries.

POST
/webhooks

Register a webhook endpoint. url must be HTTPS and event_types must list at least one event type; inbox_ids (max 10) optionally scopes the endpoint to specific inboxes (omit for all of the tenant's inboxes). Supply a client_id for idempotency — repeating a create with the same client_id returns the existing webhook (200). The response includes the endpoint's signing secret (whsec_…), returned only here — store it now to verify deliveries.

Authorization

x-api-key<token>

The per-tenant API key. Sent as the x-api-key request header. The key is tenant-scoped.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

The body for registering a webhook.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/webhooks" \  -H "Content-Type: application/json" \  -d '{    "url": "http://example.com",    "event_types": [      "message.received"    ]  }'
{  "webhook_id": "string",  "url": "http://example.com",  "event_types": [    "message.received"  ],  "inbox_ids": [    "string"  ],  "enabled": true,  "client_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "secret": "string"}
{  "webhook_id": "string",  "url": "http://example.com",  "event_types": [    "message.received"  ],  "inbox_ids": [    "string"  ],  "enabled": true,  "client_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "secret": "string"}
{  "name": "string",  "message": "string"}
{  "name": "string",  "message": "string"}
{  "name": "validation",  "errors": {    "property1": "string",    "property2": "string"  }}
{  "name": "string",  "message": "string"}

Register a webhook scoped to an inbox POST

Register a webhook pre-scoped to this inbox — the endpoint only receives events for this one inbox. Otherwise identical to `POST /webhooks`: `url` must be HTTPS, `event_types` must list at least one type, and the response includes the one-time signing secret. Supplying `inbox_ids` in the body overrides the path scope.

Delete a webhook DELETE

Delete a webhook by id; deliveries to it stop immediately and any in-flight retries are abandoned. An unknown, already-deleted, or cross-tenant id returns not-found.