Rotate a webhook endpoint's secret

POST/v1/webhook_endpoints/{wh}/rotate_secret

Issues a new signing secret and returns it; once.

The old secret keeps verifying for an overlap window (default 24h, max 168h) so deliveries in flight and receivers mid-deploy do not fail. During the window webhook-signature carries BOTH values, space-separated, and a receiver that accepts either is correct throughout.

One rotation at a time. While a previous overlap window is still open, this answers 409 rotation_in_flight. A second window would push the OLDEST secret out while your receivers may still be verifying with it: the stranding the overlap exists to prevent, so the refusal is the guarantee rather than a limitation.

Path ParametersExpand Collapse

wh: string

Query ParametersExpand Collapse

overlap_hours: optional number

How long the previous secret keeps verifying, in hours. 1–168, default 24.

formatint32

ReturnsExpand Collapse

WebhookEndpointWithSecret object { id, created_at, description, 4 more }

A newly created or newly rotated endpoint. The secret is on this response and on no other; store it now; it is never readable again, and a lost secret is replaced by rotating rather than by looking it up.

id: string

wh_….

created_at: string

formatdate-time

description: string

Your own label. Free text, ≤200 bytes, never interpreted.

enabled_events: array of string

The event types this endpoint receives. Exact names: no wildcards.

secret: string

whsec_…. Sign-verify every delivery with it. Shown once.

status: "enabled" or "disabled"

enabled while it receives deliveries, disabled once you turn it off. A disabled endpoint keeps its secret and its history and resumes on PATCH {"disabled": false}.

One of the following:

"enabled"

"disabled"

url: string

Absolute https URL every delivery for this endpoint is POSTed to.

Rotate a webhook endpoint's secret

curl https://messages.api.linqapp.com/v1/webhook_endpoints/$WH/rotate_secret \
    -X POST \
    -H "Authorization: Bearer $LINQ_AMB_API_KEY"

{
  "id": "wh_7f3a1c9e",
  "url": "https://hooks.example.com/messages",
  "description": "production receiver",
  "enabled_events": [
    "message.received",
    "message.sent",
    "message.failed"
  ],
  "status": "enabled",
  "created_at": "2026-08-13T02:41:09Z",
  "secret": "whsec_2Ld8YpVx0QaZ6nMbT3wKcR9jEsHf1uGi7oPvN4rXyBk="
}

Returns Examples

{
  "id": "wh_7f3a1c9e",
  "url": "https://hooks.example.com/messages",
  "description": "production receiver",
  "enabled_events": [
    "message.received",
    "message.sent",
    "message.failed"
  ],
  "status": "enabled",
  "created_at": "2026-08-13T02:41:09Z",
  "secret": "whsec_2Ld8YpVx0QaZ6nMbT3wKcR9jEsHf1uGi7oPvN4rXyBk="
}