Secret rotation

Rotate your signing secret on a regular schedule, and immediately if you suspect it has leaked.

POST /v1/webhooks/subscriptions/{id}/rotate-secret

The response contains the new secret and the expiry of the old one:

{
  "id":                     "a1b2c3d4-...",
  "secret":                 "whsec_newSecretValue...",
  "previousSecretExpiresAt": "2026-04-21T10:00:00.000Z"
}

Zero-downtime rotation

1. Call rotate-secret

Capture the new secret and previousSecretExpiresAt from the response.

2. Deploy the new secret

Your signature verifier already accepts either of the two signatures present in X-Webhook-Signature during the grace period.

3. Decommission the old secret

After previousSecretExpiresAt, only the new secret is valid. Remove the old one from your secret store.