Rotate a webhook signing secret
POST/organization/webhooks/{webhook_id}/rotate-secret
Issues a new signing secret, shown once in the response. For overlap_seconds (default 86400, up to 7 days; 0 for none) every delivery carries a signature for both the new and the previous secret, so a receiver holding either one can verify during the overlap. A receiver must accept the header if any v1 entry matches: the new secret's entry comes first, so a parser that reads only the last v1 gets the previous secret's signature until the overlap ends. After a leak, use 0. Rotating again during an overlap drops the older secret.
- Authentication
- Send an admin key (dk_admin_…) as a Bearer token. Data keys are refused here.
- Scope
organization- Cost
- Free
Parameters
| Name | Description |
|---|---|
webhook_idrequiredType: string · path | |
Idempotency-KeyType: string · header | A unique string (a UUID is ideal) making this call safe to retry. The same key with the same body replays the first response and sets |
Request body
| Name | Description |
|---|---|
overlap_secondsType: integer | How long the previous secret keeps signing. Default 86400. |
Response
The data field is an object with these fields.
| Name | Description |
|---|---|
idrequiredType: string | |
secretrequiredType: string | The new signing secret. Shown once. |
previous_secret_expires_atrequiredType: string (date-time) | null | When the old secret stops signing; null if it already has. |
Related endpoints
- Get your organization
GET /organization - List data keys
GET /organization/keys - Create a data key
POST /organization/keys - Revoke a key
POST /organization/keys/{key_id}/revoke - List projects
GET /organization/projects - Daily usage
GET /organization/usage - List members and invitations
GET /organization/members - List audit events
GET /organization/audit-events - List request logs
GET /organization/request-logs - Create a webhook endpoint
POST /organization/webhooks - List webhook endpoints
GET /organization/webhooks - Update a webhook endpoint
POST /organization/webhooks/{webhook_id}/update - Re-enable a webhook endpoint
POST /organization/webhooks/{webhook_id}/enable - Delete a webhook endpoint
POST /organization/webhooks/{webhook_id}/delete - List deliveries
GET /organization/webhooks/{webhook_id}/deliveries - Replay a delivery
POST /organization/webhooks/{webhook_id}/deliveries/{delivery_id}/replay