Endpoints

POST /webhooks/{id}/rotate-secret

Mint a new signing secret with a 24h grace window where both keys remain valid.

POST/api/v1/webhooks/{id}/rotate-secretsecret key

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.

Request

curl -X POST https://sandbox.key2pays.com/api/v1/webhooks/wh_3f6c7b1…/rotate-secret \
  -H "Authorization: Bearer sk_test_51N8mP...exampleK3Y"

Response

{
  "id": "wh_3f6c7b…",
  "secret": "whsec_NEW_408e8f61…",
  "previousSecret": "whsec_OLD_2zP97…",
  "previousSecretExpiresAt": "2026-05-13T18:00:00.000Z",
  "rotatedAt": "2026-05-12T18:00:00.000Z",
  "graceWindowHours": 24
}

Zero-downtime rotation workflow

Call POST /webhooks/{id}/rotate-secret. The response contains both secret (new) and previousSecret (old, expires in 24h).
Deploy your handler with BOTH secrets in its accept-list — verify against v1 first, fall back to v0 for 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.

Previous · Endpoints

DELETE /webhooks/{id}

Next · Endpoints

GET /webhooks/{id}/deliveries