> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signa.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Rotate Webhook Secret

> Roll the signing secret with a 24-hour overlap window

## 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

<ParamField path="id" type="string" required>Endpoint ID (`whk_*`).</ParamField>

## Query Parameters

<ParamField query="force" type="boolean" default="false">
  Convenience alias for `force` in the body. `?force=true` is equivalent to `{"force": true}` in the JSON body.
</ParamField>

## Body (optional)

<ParamField body="force" type="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.
</ParamField>

<ParamField body="reason" type="string">
  Optional human-readable reason (max 500 chars) recorded in the `webhook.secret.force_rotated` audit event when `force=true`. Ignored otherwise.
</ParamField>

## 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.

<RequestExample>
  ```bash cURL theme={null}
  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"
  ```

  ```bash cURL (force) theme={null}
  curl -X POST "https://api.signa.so/v1/webhooks/whk_01HK.../rotate-secret" \
    -H "Authorization: Bearer $SIGNA_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: force-rotate-whk-01HK-2026-06-12" \
    -d '{"force": true, "reason": "Suspected secret leak — incident IR-2026-04-12"}'
  ```

  ```ts TypeScript theme={null}
  const rotated = await signa.webhooks.rotateSecret('whk_01HK...');
  await secretsManager.put('SIGNA_WEBHOOK_SECRET', rotated.secret);
  ```
</RequestExample>