Documentation

Rotate a webhook's secret

POST/v1/webhooks/{webhook}/secretWebhooks

A new signing secret, shown in the answer only. The old one stops working at once.

Parameters

Parameter	Type	Required	Description
`webhook`	string, in the path	required	The endpoint's id.

Example request

curl -s -X POST "https://snip.link/v1/webhooks/webhook/secret" \
  -H "Authorization: Bearer $SNIP_KEY"

Example response

{
  "webhook": {
    "id": "5c2e7a10-3f4b-4d8e-9a61-2b7c0d4e8f13",
    "url": "https://example.com/hooks/snip",
    "description": "Orders service",
    "events": [
      "link.created",
      "link.clicked"
    ],
    "enabled": true,
    "disabled_reason": null,
    "disabled_at": null,
    "failing_since": null,
    "last_success_at": "2026-10-24T09:12:03.000Z",
    "waiting": 0,
    "created_at": "2026-10-20T12:00:00.000Z",
    "updated_at": "2026-10-20T12:00:00.000Z"
  }
}

Response fields

Field	Type	Description
`webhook`	Webhook
`webhook.id`	string
`webhook.url`	string	Where deliveries go: https, a public domain, the standard port.
`webhook.description`	string, null
`webhook.events`	link.created \| link.updated \| link.deleted \| link.clicked \| link.failing \| link.recovered \| page.changed[]
`webhook.enabled`	boolean	False while paused, or after three days in which every delivery failed.
`webhook.disabled_reason`	paused \| failing \| null	`paused` by the account, or `failing`: switched off after three days of failures.
`webhook.disabled_at`	string, null
`webhook.failing_since`	string, null	When the current run of failed deliveries began; null while the last one worked.
`webhook.last_success_at`	string, null
`webhook.waiting`	integer	Deliveries queued or waiting for a retry.
`webhook.created_at`	string
`webhook.updated_at`	string
`secret`	string	The signing secret (`whsec_...`). Shown here and nowhere else: store it where your endpoint reads it.

Errors

Status	Meaning
401	The API key is missing, malformed or revoked.
404	No webhook endpoint by that id in this account.
429	Either the key exceeded its requests-per-second limit (honor Retry-After), or a daily or plan quota is used up (`details.reason`).

Back to getting started