Rotate a webhook signing secret

Replace the endpoint's signing secret without deleting or reconfiguring the endpoint. A successful call returns the replacement exactly once; deliveries that load the endpoint afterward use it, while a delivery already in flight may still carry a signature made with the previous value. Store the returned value before leaving the response; no read operation can recover it.

The previous secret stops working at once. There is no overlap: every later delivery is signed with the replacement only. Until your receiver has it, it refuses those deliveries, and a 401 or any other 4xx answer is final and not retried, so events sent in that gap are not delivered on their own. If you can, have your receiver accept a signature made with either secret while the replacement rolls out, then drop the old one. Re-send what failed in the gap with POST /v1/webhooks/{id}/logs/{logId}/retry; a re-send is signed with the current secret.

With a dashboard session this needs a sign-in within the last 15 minutes, as changing url or events does; an older session answers 403 REAUTHENTICATION_REQUIRED. An API key or a connected app is not held to this. Each rotation is recorded in the audit log as settings.webhook_secret_regenerated, without either secret.