---
title: "Rotate the signing secret"
method: POST
path: "/v1/webhooks/{webhook_id}/secret/rotate"
tags: ["webhooks"]
---

# Rotate the signing secret

`POST /v1/webhooks/{webhook_id}/secret/rotate`

## Request

- Base URL: `https://cherami.to`
- URL: `https://cherami.to/v1/webhooks/{webhook_id}/secret/rotate`
- Auth: HTTP bearer

Creates a new signing secret and returns it. Unless `immediate` is `true`, the replaced secret keeps signing alongside the new one for 24 hours, until `previous_secret_expires_at`, so you can switch your receiver without rejecting deliveries.

Only the replaced secret is affected: a secret from an earlier rotation keeps its own 24-hour expiry, even with `immediate: true`. To stop every earlier secret now, delete the webhook and add it again.

If the response is lost, [read the webhook](https://cherami.to/docs/api/webhooks/get-webhook) before repeating: a new `secret_rotated_at` means the rotation happened, and [retrieving the secret](https://cherami.to/docs/api/webhooks/get-webhook-secret) gives you the new one.

## Path parameters

- `webhook_id` string, required

## Request body

- RotateWebhookSecret
  - `immediate` boolean: true stops the replaced secret at once.

## Response `200`

Success.

- WebhookRotation
  - `id` string, required: Cherami resource ID.
  - `secret` string, required: Signing secret for Standard Webhooks verification (whsec_...). Returned only on creation, retrieval and rotation.
  - `secret_rotated_at` string, date-time, required: UTC timestamp with milliseconds.
  - `previous_secret_expires_at` string, date-time, required: UTC timestamp with milliseconds.

## Other responses

- `400`: `invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar. `invalid_webhook_rotation`: Send an empty body or only a boolean `immediate`.
- `401`: `unauthorized`: Send a valid API key as `Authorization: Bearer <key>`. If the key stopped working, get a new one through [recovery](https://cherami.to/docs/guides/recovery).
- `404`: `not_found`: The resource does not exist or does not belong to this account. A reply or forward source must also be in the sending inbox.
- `409`: `webhook_operation_in_progress`: Another change to this webhook is in progress. Retry in a minute.
- `413`: `body_too_large`: Reduce the JSON request to the operation's body limit.
- `415`: `unsupported_media_type`: Send `Content-Type: application/json`.
- `503`: `webhook_provider_unavailable`: The request could not be completed, and nothing changed. Retry later. `webhook_rotation_uncertain`: The rotation was not confirmed and finishes within a few minutes. Then [read the webhook](https://cherami.to/docs/api/webhooks/get-webhook): a new `secret_rotated_at` means it rotated, and [retrieving the secret](https://cherami.to/docs/api/webhooks/get-webhook-secret) gives you the new one. `webhooks_unavailable`: Webhook management failed. If it was a change, it may have been applied: list or read the webhooks before repeating it.

---

[API](https://skmtc.dev/cherami/apis/cherami-http-api.md) · [All operations](https://skmtc.dev/cherami/apis/cherami-http-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cherami/apis/cherami-http-api/revisions/7bd993d538af?raw)