API referenceWebhooks
Rotate the signing secret
POST
/api/v2/webhooks/{id}/rotate-secretReplaces the secret. The response carries the new secret once. For 24 hours, deliveries carry a signature with the old secret and one with the new, so you can deploy the new secret without dropping events. Needs webhooks:write.
Path Parameters
id*string
Id of a webhook: webhook_ followed by its key.
Match
^webhook_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$Header Parameters
idempotency-key?maxLength(255)
Client-chosen key, 1 to 255 characters (a UUID is recommended). The same key on the same endpoint within 24 hours replays the stored response with Idempotent-Replayed: true.
Length
1 <= length <= 255Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v2/webhooks/webhook_0e4ba886-0bfe-4b6a-ae2e-d6d9d135dd1e/rotate-secret"{ "object": "webhook", "id": "webhook_0e4ba886-0bfe-4b6a-ae2e-d6d9d135dd1e", "url": "https://example.com/done", "events": [ "string" ], "enabled": true, "secret": "string", "createdAt": "2026-09-24T10:00:00.000Z", "updatedAt": "2026-09-24T10:00:00.000Z"}