Skip to main content
This endpoint generates a new webhook signing secret for a subscription. To avoid dropping deliveries during a key rotation, you can specify a grace period during which the service signs each delivery with both the old and the new secret. Your endpoint can then validate against either, giving you time to deploy the new secret without downtime.

​
Request

​
Headers

​
Path parameters

​
string
required
The subscription ID (e.g. sub_2QkP9aB7xN...).

​
Body

​
integer
How long, in seconds, the old secret remains valid alongside the new one. Set to 0 for an immediate cutover — the old secret becomes invalid as soon as the request completes. Defaults to 0.

​
Response

200 OK — the newly generated secret.
The new secret is returned only in this response. Store it immediately before making any other API calls. After the grace period ends, the old secret is invalid and cannot be recovered.

​
During the grace period

While the grace period is active, the webhook-signature delivery header contains space-separated v1, signatures for both secrets:
The Svix verification library handles multi-signature validation automatically — you do not need to change your verification code during the transition.

​
Idempotency

Use the Idempotency-Key header to safely retry this request if you receive a network error or timeout. If the server has already processed a request with the same key, it returns the cached response without generating a new secret. Sending a conflicting body with the same key returns idempotency_conflict.

​
Errors