Rotate an endpoint's signing secret
Mint a fresh signing secret for one endpoint. The new secret is returned
base64-encoded in the secret field exactly once.
The previous secret is replaced immediately. There is no grace window on
per-endpoint rotation, unlike the per-organization secret at
POST /v1/webhook-secret/rotate, which keeps the previous secret valid
for 5 minutes.
To rotate without mis-signing in-flight deliveries, either rotate during
a maintenance window, or stand up a new endpoint, validate it end-to-end
with POST /v1/webhooks/{id}/test, and delete the old one.
Requires the webhooks:write scope.
Authenticate by sending your API key as a bearer token:
Authorization: Bearer am_live_.... Every request is automatically
scoped to the organization that owns the key and to the scopes granted
to that key.
In: header
Path Parameters
uuidResponse Body
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/webhooks/497f6eca-6276-4993-bfeb-53cbbbba6f08/rotate-secret"{
"id": "0190a1b2-c3d4-e5f6-a7b8-c9d0e1f2a3b4",
"org_id": "0190a1b2-c3d4-e5f6-a7b8-c9d0e1f2a3b5",
"url": "https://hooks.example.com/y3labs/ops",
"events": [
"wallet.balance_low"
],
"active": true,
"api_version": "2026-04-01",
"created_at": "2026-04-26T12:00:00Z",
"updated_at": "2026-04-29T09:30:00Z",
"deleted_at": null,
"secret": "BU3aA56KLn/gYzL+2yE0kZ9wD3jA2QAnLaWKkjNl8Z0=",
"secret_displayed_once": true
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "authentication failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "missing required scope",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "not found",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}