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).
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.
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
descriptionentity_identity_typesigning_methodCreate a webhook secret › Responses
Created
Delete a webhook secret
path Parameters
idWebhook secret UUID
Webhook 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.
path Parameters
idWebhook secret UUID
Webhook 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