Webhook secrets are the HMAC signing keys used to authenticate inbound webhook payloads. Each secret is scoped to an entity (e.g., a specific integration endpoint) and can be rotated without downtime by creating a new secret before deactivating the old one.
List webhook secrets
Returns a paginated list of webhook secrets with key_prefix only (signing_key is never included).
Required scope: webhook.read (Read webhooks).
query Parameters
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List webhook secrets › Responses
OK
Create a webhook secret
Creates a new webhook signing secret. The full signing_key is returned only once and cannot be retrieved again.
Required scope: webhook.write (Manage webhooks).
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Create a webhook secret › Request Body
descriptionThe record the secret belongs to. Required, here or as entity_type and entity_id.
signing_methodentity_idThe record's id, under its old name. Deprecated: use entity.id instead. Removed on 2026-11-30.
entity_typeThe kind of record the secret belongs to, under its old name. Sent with entity, both must name the same record. Deprecated: use entity.type instead. Removed on 2026-11-30.
Create a webhook secret › Responses
Created
Delete a webhook secret
Permanently deletes the signing secret and answers 204. A secret that an endpoint still signs with is refused with 409; point that endpoint at another secret, or delete it, first. An unknown id, or one from another organization, answers 404.
Required scope: webhook.write (Manage webhooks).
path Parameters
idWebhook secret UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Delete a webhook secret › Responses
No Content
Rotate a webhook signing secret
Generates a new signing key for the secret, replaces it in place, and returns the plaintext key exactly once. The old key stops working immediately - no grace window. The (entity_type, entity_id) tuple is preserved so downstream consumers don't need to re-fetch the secret_id.
Required scope: webhook.write (Manage webhooks).
path Parameters
idWebhook secret UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Rotate a webhook signing secret › Responses
OK