---
search:
  tags:
    - Webhooks
    - POST
seo:
  description: >-
    BillionSend extension. Mints a new signing secret (or takes the one in…
    Reference for the POST /webhooks/{id}/rotate endpoint in the BillionSend
    API.
sidebar:
  label: Rotate signing secret
  badge: POST
title: Rotate signing secret
type: openapi-operation
---
BillionSend extension. Mints a new signing secret (or takes the one in signing_secret) and returns it. For overlap_hours the previous secret keeps signing too: every delivery in that window carries both signatures, space-separated in webhook-signature, so the receiver can switch at any point without a gap. A second rotation inside the window replaces the previous secret.

`POST /webhooks/{id}/rotate`

**Request body** (`application/json`)

- `signing_secret` (string) — New secret to sign with: whsec\_ followed by base64 of 24-64 bytes. Omit to mint one.
- `overlap_hours` (integer) — Hours the previous secret keeps signing alongside the new one (default 24, max 72). Every delivery in the window carries both signatures, so a receiver holding either verifies; 0 drops the old secret at once.

Request body example:

```json
{
  "signing_secret": "string",
  "overlap_hours": 0
}
```

**Responses**

- `200` — The new secret and when the previous one stops signing
- `401` — Missing, malformed, unknown or revoked API key
- `404` — Not found
- `422` — Validation error
- `429` — Over the rate limit (rate\_limit\_exceeded, with Retry-After)

Response example, 200:

```json
{
  "object": "webhook",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "signing_secret": "string",
  "previous_secret_expires_at": "string"
}
```
