Rotate the signing secret
Mints a new webhook signing secret, returns it exactly once, persists it as the current secret, and demotes the previous secret with a 24-hour overlap during which both remain valid for verification. Delivery signs with the current secret. A subscription with no signing secret at rest (a pull sink) returns 422 no_secret_to_rotate.
Authorizations
A bearer JWT issued by plugin-auth (lib-auth). The tenant identity is resolved from the validated token claims; the /v1 surface never reads a tenant from the body, path, or query. Machine callers obtain a token via the plugin-auth client-credentials flow. The /admin surface authorizes against an operator scope and carries no tenant context.
Headers
A client-chosen unique key that makes this mutation at-most-once. A mutation sent without it is rejected before any write with 400 missing_idempotency_key. Reusing the same key with an identical request replays the original response byte-for-byte (with X-Idempotency-Replayed: true); reusing it with a different request body returns 409 idempotency_conflict. To re-drive a corrected request, mint a new key.
Path Parameters
The unique identifier of the subscription (UUIDv7).
Response
A new signing secret was minted. signingSecret is shown exactly once — save it on receipt.
The new one-time signing secret (write-only). Shown exactly once here.
"whsec_1a2b3c4d5e6f7081a2b3c4d5e6f70819"
The moment the previous secret stops being valid for verification (UTC, RFC 3339) — a 24-hour dual-sign overlap.
"2026-06-06T12:00:00Z"

