Rotate webhook secrets
Who this is for: admins who manage webhook endpoints, for example after a secret leaked or on a regular schedule.
Before you start: you must be signed in as a person with the Manage webhooks permission. To show the new secret you need the Reveal secrets permission. AI assistants and API tokens cannot rotate or show secrets.
Rotating makes a new signing secret. The previous secret keeps working for a grace period, so you have time to give the new one to the sender. No delivery is lost if you update the sender before the grace period ends.
- Open Webhooks and select the endpoint.
- Under Signing secret, select Rotate secret.
- Set Grace period in hours: 0 to 168. The default is 24. 0 stops the previous secret at once: use it when the old secret leaked.
- Select Rotate. The page shows until when the previous secret still works.
- Select Show secret. You see the Current secret and the Previous secret (works until …). Copy the current one. The values hide again after 30 seconds, and every showing is written to the audit log.
- Put the new secret into the sender (its settings, or its secret store).
- Send a test delivery to check it. See Check that it works.
During the grace period
Section titled “During the grace period”- Liitora accepts deliveries signed with either secret.
- A sender that uses the Liitora scheme may send both signatures in one header while it switches:
X-Liitora-Signature: sha256=<new>,sha256=<old>. Up to 5 signatures are allowed and one must match. - For Bearer token and Username and password endpoints, both the old and the new secret are accepted as the token or password.
- It can take up to about 10 seconds before the webhook receiver uses the new secret.
When the grace period ends
Section titled “When the grace period ends”Deliveries signed with the previous secret get 401 with the code unauthorized. The sender must use the new secret. If you missed it, rotate again: there is no way to bring the old secret back.
Stripe endpoints
Section titled “Stripe endpoints”Stripe creates the signing secret of a Stripe endpoint, so Rotate secret does not apply to it (the error is provider_managed_secret).
- In the Stripe Dashboard, open the webhook endpoint and roll its signing secret. Stripe can keep the old secret valid for a while.
- Copy the new secret.
- In Liitora, open Secrets, find the endpoint’s secret and select Rotate. Paste the new value.
With the API
Section titled “With the API”People can also rotate through the API while signed in: POST /api/v1/webhook-endpoints/{id}/rotate-secret with {"grace_hours": 24}. API tokens are refused.