API ReferenceWebhooksRotate a webhook signing secret

Rotate a webhook signing secret

POST/api/v1/webhooks/{webhook_id}/rotate idempotent

Generates a fresh whsec_* signing secret and replaces the encrypted blob on the endpoint doc. The new plaintext secret is returned EXACTLY ONCE — capture it. Endpoint id, url, events, and delivery history are preserved. Recommended pattern: customer accepts both old + new secrets for a brief overlap window while in-flight deliveries drain.

Parameters

webhook_id*

stringpath

Responses

Success body

{
  "status": 200,
  "message": "OK",
  "data": {
    "id": "IM-2026-0528-9ZNCP3-1",
    "rotated_at": "2026-05-28T07:44:23.908Z",
    "secret": "whsec_y7f0MNv_u0ARXlAJSOxTiaRfjyv9eWJQBlbdrlzRED8",
    "secret_last4": "RED8"
  }
}

Returned object

Field	Type	Sample
status	number	200
message	string	OK
data	object	{4 keys}