Webhooks

Outbound subscriptions to the platform's events, their signing secret and the delivery attempts they produced. Eleven tools — the largest resource.

See the Webhook model, the WebhookDelivery model and Webhook security for HMAC signature validation.

---

webhooks_list

Read · scope inbox/webhooks · permission webhooks.list · GET /webhooks

List webhook subscriptions. Signing secrets are never returned.

Parameter	Type	Description
cursor	string	Opaque cursor from a previous page.
limit	integer	Page size, default 25, max 100.
sort	string	Sort keys, - prefix for descending.
status	active | inactive	Filter by status.
inbox_id	string (uuid)	Only subscriptions scoped to this inbox.
external_id	string	Filter by the id in your system.
created_at_gte / created_at_lte	string	ISO 8601 range on created_at.

webhooks_get

Read · scope inbox/webhooks · permission webhooks.show · GET /webhooks/{id}

Fetch one webhook by internal id or external_id.

Parameter	Type	Description
id required	string	Internal id or external_id.

webhooks_create

Write · scope inbox/webhooks + write · permission webhooks.create · POST /webhooks

Create a webhook subscription. The response carries signing_secret in clear text exactly once — surface it to the user immediately, it cannot be read back.

Parameter	Type	Description
label required	string	Display name, 1–120 chars.
url required	string	Destination URL.
external_id	string	Id of the record in your system.
inbox_id	string (uuid) | null	Scope the subscription to one inbox; null means the whole workspace.
subscribed_events	string[]	Event slugs to subscribe to.
auth	none | basic | bearer | header	Authentication scheme used when calling your endpoint.
auth_basic_user	string	Username, for basic.
auth_basic_password	string	Password, for basic.
auth_bearer_token	string	Token, for bearer.
auth_header_key	string	Header name, for header.
auth_header_value	string	Header value, for header.
signing_secret	string	Bring your own secret (whsec_…); generated when omitted.
custom_metadata	object	Free-form JSON owned by the caller.
idempotency_key	string	Replay guard, 8–255 chars.

webhooks_upsert

Write · scope inbox/webhooks + write · permission webhooks.create · PUT /webhooks

Create or update a webhook, matched by id then external_id. An auth block replaces the stored one wholesale; a signing_secret rotates it and is returned once.

Parameter	Type	Description
id	string (uuid)	Match by internal id first.
external_id	string	Match key in your system.
label	string	Display name, 1–120 chars.
url	string	Destination URL.
inbox_id	string (uuid) | null	Scope to one inbox, or null for the workspace.
subscribed_events	string[]	Event slugs to subscribe to.
auth	none | basic | bearer | header	Authentication scheme.
auth_basic_user	string	Username, for basic.
auth_basic_password	string	Password, for basic.
auth_bearer_token	string	Token, for bearer.
auth_header_key	string	Header name, for header.
auth_header_value	string	Header value, for header.
signing_secret	string	Rotates the secret; returned once.
custom_metadata	object	Free-form JSON.
idempotency_key	string	Replay guard.

webhooks_update

Write · scope inbox/webhooks + write · permission webhooks.update · PATCH /webhooks/{id}

Update a webhook subscription in place.

Parameter	Type	Description
id required	string	Internal id or external_id.
label	string	Display name, 1–120 chars.
url	string	Destination URL.
external_id	string	Id in your system.
inbox_id	string (uuid) | null	Scope to one inbox, or null for the workspace.
subscribed_events	string[]	Event slugs to subscribe to.
auth	none | basic | bearer | header	Authentication scheme.
auth_basic_user	string	Username, for basic.
auth_basic_password	string	Password, for basic.
auth_bearer_token	string	Token, for bearer.
auth_header_key	string	Header name, for header.
auth_header_value	string	Header value, for header.
custom_metadata	object	Free-form JSON.

webhooks_delete

Destructive · scope inbox/webhooks + write · permission webhooks.delete · DELETE /webhooks/{id}

Soft-delete a webhook subscription. Pending deliveries stop.

Parameter	Type	Description
id required	string	Internal id or external_id.

webhooks_test

Destructive · scope inbox/webhooks + write · permission webhooks.test · POST /webhooks/{id}/test

Send a synthetic webhook.ping through the real signing and retry path, so you can validate URL and authentication. Answers 202.

Parameter	Type	Description
id required	string	Internal id or external_id.
idempotency_key	string	Replay guard, 8–255 chars.

webhooks_regenerate_secret

Destructive · scope inbox/webhooks + write · permission webhooks.rotate-secret · POST /webhooks/{id}/regenerate-secret

Rotate the signing secret. The new one is returned once; the previous secret keeps validating during the grace window.

Parameter	Type	Description
id required	string	Internal id or external_id.
idempotency_key	string	Replay guard, 8–255 chars.

webhooks_deliveries_list

Read · scope inbox/webhooks · permission webhooks.show · GET /webhooks/{id}/deliveries

Delivery attempts for one webhook, with HTTP status and attempt number.

Parameter	Type	Description
id required	string	Webhook internal id or external_id.
cursor	string	Opaque cursor from a previous page.
limit	integer	Page size, default 25, max 100.
sort	string	Sort keys, - prefix for descending.
status	pending | success | failed	Filter by delivery status.
attempt	integer	Filter by attempt number.
response_status	integer	Filter by the HTTP status your endpoint answered.
system_event_id	string (uuid)	Only deliveries of this event.
created_at_gte / created_at_lte	string	ISO 8601 range on created_at.

webhooks_deliveries_get

Read · scope inbox/webhooks · permission webhooks.show · GET /webhooks/{id}/deliveries/{delivery_id}

Fetch one delivery attempt, including request and response headers and bodies.

Parameter	Type	Description
id required	string	Webhook internal id or external_id.
delivery_id required	string (uuid)	Delivery id.

webhooks_deliveries_replay

Destructive · scope inbox/webhooks + write · permission webhooks.replay · POST /webhooks/{id}/deliveries/{delivery_id}/replay

Re-send one delivery with a fresh signature. Answers 202.

Parameter	Type	Description
id required	string	Webhook internal id or external_id.
delivery_id required	string (uuid)	Delivery id.
idempotency_key	string	Replay guard, 8–255 chars.