Skip to main content
POST
/
v1
/
webhooks
/
{id}
/
rotate-secret
curl -X POST "https://api.signa.so/v1/webhooks/whk_01HK.../rotate-secret" \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  -H "Idempotency-Key: rotate-whk-01HK-2026-06-12"

​
Overview

Rotates the signing secret. The new secret is returned once in the response. The previous secret remains valid for 24 hours, during which the dispatcher signs every delivery with both — webhook-signature: v1,<new> v1,<old> (SPACE-separated, per Standard Webhooks spec). Update your verifier to the new secret any time within the window; missed deliveries are impossible.

​
Path Parameters

​
id
string
required
Endpoint ID (whk_*).

​
Query Parameters

​
force
boolean
default:"false"
Convenience alias for force in the body. ?force=true is equivalent to {"force": true} in the JSON body.

​
Body (optional)

​
force
boolean
default:"false"
EMERGENCY USE ONLY. When true, skip the 24h previous-secret overlap window and immediately invalidate the previous secret. Any receiver still using the previous secret will fail signature verification on the next delivery. Without force, attempting to rotate while the previous secret is still in its 24h overlap window returns 409.
​
reason
string
Optional human-readable reason (max 500 chars) recorded in the webhook.secret.force_rotated audit event when force=true. Ignored otherwise.

​
Response

A Webhook with the new secret and bumped secret_version.

​
Errors

  • 404 — endpoint does not exist or belongs to another org.
  • 409 — previous-secret 24h overlap is still active and force=true was not supplied. Wait for the window to close, or pass force=true for emergency rotation.
curl -X POST "https://api.signa.so/v1/webhooks/whk_01HK.../rotate-secret" \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  -H "Idempotency-Key: rotate-whk-01HK-2026-06-12"