---
title: "Rotate a webhook's signing secret"
method: POST
path: "/v1/webhooks/{id}/rotate-secret"
tags: ["Webhooks"]
---

# Rotate a webhook's signing secret

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

## Request

- Base URL: `https://api.honkio.ca`
- URL: `https://api.honkio.ca/v1/webhooks/{id}/rotate-secret`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Generates a new signing secret and returns it once. The previous secret stops signing at once. Every delivery attempt, retries included, is signed with the secret the endpoint holds at that moment, so return a non-2xx for a signature you cannot verify and the retry arrives signed with the new secret.

Requires `webhooks:m`.

## Path parameters

- `id` string, required

## Response `200`

The new secret, shown only here. The previous secret stops signing at once; retries of anything the endpoint rejects during the switch are re-signed with this one.

- object: The new secret, shown only here. The previous secret stops signing at once; retries of anything the endpoint rejects during the switch are re-signed with this one.
  - `id` string, required
  - `signing_secret` string, required: 64 hex characters.
  - `secret_rotated_at` string, date-time, required
  - `notice` string, required

## Other responses

- `401`: Missing, invalid, revoked or expired API key.
- `402`: The account has no balance, or a LIVE key was used before the first top-up.
- `403`: LIVE_KEY_REQUIRED: test keys cannot reach live resources here. Also FORBIDDEN when the key lacks the permission this operation requires, or the account is suspended or closed.
- `404`: NOT_FOUND: no such resource on this account.
- `429`: Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).
- `500`: Unexpected server error.

---

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