Rotate a webhook's signing secret
Generates a new signing secret and returns it once. The previous secret remains valid for 24 hours
(previous_valid_until): during that window, every delivery carries two space-separated signatures
in webhook-signature, one per secret, so a receiver still configured with the previous secret
continues to verify requests while the new one is deployed. After the window, only the new secret
signs.
Rotating again within the window replaces the previous secret with the one that was current, so at most two secrets are valid at any time.
Rotating a signing secret is a credential operation: a leaked API key must not be able to re-sign deliveries with a secret the receiver does not know. API keys are rejected regardless of scope.
Side effects. Replaces the stored secret (encrypted at rest) and keeps the previous one for 24 hours. Written to the audit log, with the secret redacted.
Idempotency. Not idempotent. Every call issues a different secret. If the response is lost, rotate again and use the most recent secret.
Webhook events. Emits audit.log_recorded to endpoints 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 an active subscription (
active,trialingorpast_due); without one the request is refused with403 BILLING_ERROR(metadata.kind: subscription_required). See Billing and usage.
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.
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.
Path parameters
UUID of the outbound webhook endpoint, returned as id by GET /api/webhooks. It must belong to the authenticated workspace; an id from another workspace, an unknown id or a value that is not a UUID answers 404.