API reference
Rotate webhook secret
Mint a new signing secret with a 24h grace window where both keys remain valid.
POST
/api/v1/webhooks/{id}/rotate-secretStep-by-step guideStep 1 of 3
Select a stage to see what happens.
Your integration
Request readyIllustrative example
POST
/webhooks/{id}/rotate-secret- Authorization
- Bearer ••••••••
- Accept
- application/json
Prepare the request
Use credentials for the selected environment and complete the required parameters.
Illustrative flow · no data is sent
How this endpoint works
Rotate the HMAC signing key. The new secret is returned ONCE; the old one stays valid for 24 hours so you can deploy the new key to your handler without dropping deliveries. During the grace window every event arrives with TWO signatures in the `X-Key2Pay-Signature` header — `v1=<hash-with-new>,v0=<hash-with-old>` — and your handler should accept either.
Server-side authentication
Authentication guideIntegration details
Currency, behavior and additional notes for this operation.
Zero-downtime rotation workflow
- Call
POST /webhooks/{id}/rotate-secret. The response contains bothsecret(new) andpreviousSecret(old, expires in 24h). - Deploy your handler with BOTH secrets in its accept-list — verify against
v1first, fall back tov0for the grace window. - After 24h our dispatcher stops including
v0. The old secret can be removed from your accept-list.
If the OLD secret was leaked (which is why you're rotating), the 24h window is also a 24h exposure window — any actor who has the old key can still forge valid signatures during that time. For an emergency rotation where you want the old key invalid IMMEDIATELY, rotate once and then
PATCH active: false until you've deployed; re-enable when the new key is live on your end.