← API referenceChanges & events · API access unavailable
API REFERENCE / CHANGES & EVENTS
POST /v1/webhooks/{webhook_id}/rotate-secret
Start signing-secret rotation for a webhook without losing event delivery.
Request fields
| Location | Field | Type | Required | Description |
|---|---|---|---|---|
| Header | Authorization | string | Yes | Credential scoped to the authorized resource. |
| Path | webhook_id | string | Yes | Webhook owned by this integration. |
| Header | Idempotency-Key | string | Yes | Stable retry identity. |
Request example
Example request
POST /v1/webhooks/wh_123/rotate-secret
Authorization: Bearer <scoped token>
Idempotency-Key: rotate-8427HTTP status codes
| Status | Meaning |
|---|---|
202 Accepted | Success response shown below. |
401 Unauthorized | Missing, expired, or invalid credential. |
403 Forbidden | Credential is valid but lacks the required scope or role. |
404 Not Found | Webhook is not visible to this integration. |
409 Conflict | Rotation already pending. |
429 Too Many Requests | Rate limit reached; honor Retry-After when provided. |
503 Service Unavailable | Service temporarily unavailable; retry safely. |
Response fields
| Field | Type | Example |
|---|---|---|
id | string | wh_123 |
status | string | rotating |
rotation_id | string | rotation_123 |
Response example
Example response
202 Accepted
Content-Type: application/json
{
"id": "wh_123",
"status": "rotating",
"rotation_id": "rotation_123"
}How it works
The exact one-time secret handoff, old/new overlap window, and lost-acknowledgement recovery are unresolved security decisions; this example intentionally does not return a secret.