Generate a new signing secret for your webhook subscription. The new secret immediately replaces the previous one and is assigned a fresh key identifier (webhook_secret_kid); any signature computed with the old secret stops validating right away. The plaintext secret is returned only once in this response, so store it securely before discarding the response.

Authentication & access

• Requires a client API token: Authorization: Bearer <token>.
• The caller must hold the webhooks.secret.rotate permission and have the OWNER or DEVELOPER role.

Step-up verification (dashboard sessions only)

When the call is made with a dashboard account token, rotating the secret is a sensitive action and requires a completed step-up verification challenge. Supply the challenge headers:

• X-Security-Token — the challenge token issued when the verification challenge was started.
• X-Security-Code — the one-time verification code.
• X-Security-Method — the verification method used for the challenge.

If the headers are missing, the token is not a dashboard account, or the challenge does not match this operation, the request is rejected with 403. An invalid or expired challenge, a wrong code, or a method mismatch returns 400. Requests made with a regular API token do not require these headers.

Response

Returns 200 with:

• webhook_secret — the new plaintext signing secret. Shown only in this response; it cannot be retrieved again.
• webhook_secret_kid — the key identifier for the new secret.
• message — a confirmation message.

Rotating also updates the subscription's webhook_secret_rotated_at and webhook_updated_at timestamps (visible via the subscription endpoint).

Error responses

Standard 401 (authentication), 403 (insufficient permission or role), and 429 (rate limit) responses apply to every endpoint and are documented in the Error reference.