Rotate a webhook's signing secret

Rotating a signing secret counts as a credential operation. A leaked API key must not be able to take over your integration this way, so API keys are always refused here, whatever their scope.

Side effects. Replaces the stored secret (encrypted at rest). Written to the audit log as webhook.rotate_secret, with the secret redacted.

Idempotency. Not idempotent. Every call issues a different secret and invalidates the previous one. If the response is lost, rotate again and use the newest secret.

Webhook events. Emits audit.log_recorded to webhooks subscribed to it. See Webhooks.

Access

Required scope: Not available to API keys (signed-in owner/admin session only).
Rate limit: General API (120–600 requests/min per workspace, by plan) plus the configuration-mutations limit — 10 requests/min per workspace, shared with other configuration changes. See Rate limits.
Plan: Requires the webhook plan feature. Every plan includes it today, so this gate currently refuses nobody.

Generates a new signing secret and returns it in plaintext. The old secret stops being used immediately. That includes retries of events queued before the rotation, which are signed with the new secret when they are sent. There is no overlap period, so deploy the new secret to your receiver right away, or accept both secrets there for a short window before rotating. Rotating a signing secret counts as a credential operation. A leaked API key must not be able to take over your integration this way, so API keys are always refused here, whatever their scope. **Side effects.** Replaces the stored secret (encrypted at rest). Written to the audit log as `webhook.rotate_secret`, with the secret redacted. **Idempotency.** Not idempotent. Every call issues a different secret and invalidates the previous one. If the response is lost, rotate again and use the newest secret. **Webhook events.** Emits `audit.log_recorded` to webhooks subscribed to it. See [Webhooks](/webhooks). **Access** - **Required scope:** Not available to API keys (signed-in owner/admin session only). - **Rate limit:** General API (120–600 requests/min per workspace, by plan) plus the configuration-mutations limit — 10 requests/min per workspace, shared with other configuration changes. See [Rate limits](/rate-limits). - **Plan:** Requires the `webhook` plan feature. Every plan includes it today, so this gate currently refuses nobody.

Authentication

AuthorizationBearer

Workspace API key: jl_ followed by 64 lowercase hex characters, created by the workspace owner in the dashboard (Settings → API Keys) and sent as Authorization: Bearer jl_.... The plaintext is shown once, at creation; Jelliu stores only a SHA-256 hash. A workspace can hold up to 25 active keys.

Scope	GET / HEAD	POST / PUT / PATCH / DELETE	Admin-only routes
`read`	Yes	No	No
`write`	Yes	Yes	No
`full`	Yes	Yes	Yes

Operations restricted to admins or owners reject keys without the full scope with 403, and say so in their description. No key, whatever its scope, can mint or revoke API keys or rotate a webhook secret — that requires a signed-in owner session. A revoked key stops authenticating within about 10 seconds. See Authentication.

Workspace API key: `jl_` followed by 64 lowercase hex characters, created by the workspace owner in the dashboard (**Settings → API Keys**) and sent as `Authorization: Bearer jl_...`. The plaintext is shown once, at creation; Jelliu stores only a SHA-256 hash. A workspace can hold up to 25 active keys. | Scope | GET / HEAD | POST / PUT / PATCH / DELETE | Admin-only routes | | --- | --- | --- | --- | | `read` | Yes | No | No | | `write` | Yes | Yes | No | | `full` | Yes | Yes | Yes | Operations restricted to admins or owners reject keys without the `full` scope with `403`, and say so in their description. No key, whatever its scope, can mint or revoke API keys or rotate a webhook secret — that requires a signed-in owner session. A revoked key stops authenticating within about 10 seconds. See [Authentication](/authentication).

Path parameters

webhookIdstringRequiredformat: "uuid"

UUID of the outbound webhook. It must belong to the authenticated workspace; an id from another workspace answers 404, exactly like an unknown one. Returned as id by GET /api/webhooks.

Response

The new secret, shown only in this response.

dataobject

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error