# Rotate a webhook endpoint's secret

`POST /v1/webhooks/{id}/rotate-secret`

Gives the webhook endpoint a new signing secret.

Needs `webhooks:write`.

## Path parameters

- `id` (string, uuid): The webhook endpoint's ID.

## Body

- `overlap_hours` (integer): How long the old secret keeps signing. 0 stops it at once. From 0 to 168. Default `24`.

## Headers

- `Idempotency-Key` (string): Makes this request safe to retry. See [Retrying safely](/reference/api/#retrying-safely). 1 to 255 characters.

## Switching over

The old secret keeps signing for `overlap_hours`. Meanwhile every request carries both signatures in `webhook-signature`, separated by a space, so you can switch over without missing an event.

## Example

```sh
curl -X POST https://app.soosh.io/v1/webhooks/4c6e8a0c-2e4b-4d6f-b8a0-1c3e5a7c9e4b/rotate-secret \
  -H "Authorization: Bearer $SOOSH_API_KEY" \
  -H "Idempotency-Key: rotate-webhook-secret-example-1" \
  -H "Content-Type: application/json" \
  -d '{
    "overlap_hours": 24
  }'
```

Response 200:

```json
{
  "secret": "whsec_C2FVsBQIhrscChlQIMV+b5sSYspob7oD9uXe4RkZ1aM=",
  "previous_secret_expires_at": "2026-10-15T09:45:12.340Z"
}
```

## Returns

200. The new secret, shown this once, and when the old one stops signing.

## Errors

Besides the ones every request can get (https://docs.soosh.io/reference/api/errors/):

- 422 `invalid_field`: The `overlap_hours` is outside 0 to 168.
- 403 `scope_missing`: The key lacks the read scope of an event the endpoint sends.
- 404 `not_found`: There is no webhook endpoint with this ID in your workspace.
- 409 `idempotency_in_progress`: A request with the same `Idempotency-Key` is still running.
- 422 `idempotency_mismatch`: The `Idempotency-Key` was used before for a different request, or by another of your API keys.