Skip to main content
POST
/
api
/
webhooks
/
subscriptions
/
{id}
/
rotate-secret
Rotate signing secret
curl --request POST \
  --url https://api.example.com/api/webhooks/subscriptions/{id}/rotate-secret \
  --header 'Authorization: <authorization>'
{
  "id": "1c84203c-b4e3-40de-83a9-51bc0d9c991f",
  "secret": "whsec_Qx9_NK7gh-ZbR43210uVdMcEw2pf3CYn5pAUmeU1XYW8",
  "secretPrefix": "whsec_Qx9_NK"
}
Mints a new whsec_… secret and returns it once. The previous secret is invalidated immediately — there is no overlap window. If you need overlap (e.g. rolling deploys), use this flow:
  1. Pause the subscription.
  2. Rotate the secret here.
  3. Deploy your verifier with the new secret.
  4. Unpause the subscription via Update.
Scope webhooks:write · rate-limited

​
Headers

​
Authorization
string
required
API key.

​
Path parameters

​
id
string
required
Subscription UUID.

​
Response

​
id
string
Subscription UUID.
​
secret
string
The new signing secret in plaintext. Returned only here — store it immediately.
​
secretPrefix
string
First few characters of the new secret.
{
  "id": "1c84203c-b4e3-40de-83a9-51bc0d9c991f",
  "secret": "whsec_Qx9_NK7gh-ZbR43210uVdMcEw2pf3CYn5pAUmeU1XYW8",
  "secretPrefix": "whsec_Qx9_NK"
}