---
title: "Rotate Webhook Secret"
method: POST
path: "/v1/webhooks/secret/rotate"
tags: ["keys"]
---

# Rotate Webhook Secret

`POST /v1/webhooks/secret/rotate`

## Request

- Base URL: `https://api.craterview.ai`
- URL: `https://api.craterview.ai/v1/webhooks/secret/rotate`
- Auth: HTTP bearer

Replace the signing secret, without breaking the receiver you have deployed.

The secret you were using keeps being sent alongside the new one for a window, so every
delivery in that period carries a signature under each and a receiver verifying against
either passes. Deploy the new secret whenever it suits you; nothing fails in between.

Rotating twice inside one window drops the older of the two — the window is what a
receiver is given, not a chain to accumulate.

## Response `200`

Successful Response

- WebhookSecret: The secret this account's callbacks are signed with.
  - `secret` string, required: Verify a delivery by computing HMAC-SHA256 of `<CV-Timestamp>.<body>` under this value and looking for the result among the comma-separated values in `CV-Signature`.
  - `previous` string, nullable: The secret this one replaced, while it is still being sent alongside. Null unless a rotation's window is open.
  - `overlap_ends_in_seconds` number, nullable: How much longer deliveries carry a signature under `previous`. Null when no rotation is in progress.

## Other responses

- `400`: the path, query or a JSON string in the body contains a NUL character or an unpaired surrogate; the body is not JSON encoded as UTF-8, or carries a number JSON cannot represent (NaN, Infinity, or one too large) or nesting too deep to read; or an Idempotency-Key header is longer than 255 characters or not printable ASCII. The request was not read
- `401`: missing, malformed or unrecognised API key
- `404`: the account behind this key no longer exists
- `413`: the request body is larger than 1 MiB. The request was not read

---

[API](https://skmtc.dev/craterview/apis/craterview-ai-api.md) · [All operations](https://skmtc.dev/craterview/apis/craterview-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/craterview/apis/craterview-ai-api/revisions/9419a5cd27cd?raw)