# Rotate a webhook signing secret.

`POST /webhooks/{id}/rotate_secret`

> Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-rotate-webhook-secret · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmRotateWebhookSecret` · Tag: Webhooks

Issues a new signing secret and returns it. Use this if the current secret has leaked or been lost.

The old secret stops being valid immediately, so deliveries signed with the new secret will fail verification until your endpoint is using it. Deploy the new secret promptly after rotating.

## Request

`POST https://api.usewheelhouse.com/ss_api/v1/webhooks/{id}/rotate_secret`

Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | yes | The Wheelhouse internal subscription ID. |

### Example request

```bash
curl -X POST 'https://api.usewheelhouse.com/ss_api/v1/webhooks/{id}/rotate_secret' \
  -H 'X-Integration-Api-Key: <your RM API key>'
```

Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say.

## Responses

### 201

The subscription, including its new signing secret.

Body (`application/json`): object `webhook_with_secret`

A registered webhook subscription.

A subscription including its signing secret. Returned only on creation and by
`POST /webhooks/{id}/rotate_secret`; store it, because it cannot be read back.

- `id` (integer, required): The Wheelhouse internal subscription ID.
- `url` (string, required, example: `https://example.com/wheelhouse/webhooks`): The HTTPS endpoint deliveries are posted to.
- `description` (string, nullable): Label for this subscription.
- `event_types` (array of string, required): The event types this subscription receives.
- `enabled` (boolean, required): Whether deliveries are being sent. Set to `false` automatically after sustained
  delivery failures; re-enable with `PUT /webhooks/{id}`.
- `consecutive_failures` (integer): Failed deliveries since the last successful one. Reset on success.
- `disabled_at` (string (date-time), nullable): When the subscription was disabled, automatically or otherwise (ISO-8601).
- `last_delivered_at` (string (date-time), nullable): When a delivery to this endpoint last succeeded (ISO-8601).
- `created_at` (string (date-time)): When the subscription was created (ISO-8601).
- `secret` (string, required, example: `whsec_0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0`): Secret used to verify the `Wh-Signature` header on each delivery. Recompute
  `HMAC-SHA256(secret, "<t>.<raw body>")` and compare.

Example shape (generated from the schema; placeholder values, not a real response):

```json
{
  "id": 0,
  "url": "https://example.com/wheelhouse/webhooks",
  "description": "string",
  "event_types": [
    "string"
  ],
  "enabled": true,
  "consecutive_failures": 0,
  "disabled_at": "2026-01-01T00:00:00Z",
  "last_delivered_at": "2026-01-01T00:00:00Z",
  "created_at": "2026-01-01T00:00:00Z",
  "secret": "whsec_0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0"
}
```

### 401

API key authorization failed.

### 403

The API key is read-only and may not be used to rotate a secret.

### 404

No such webhook subscription for this user.

### 409

A concurrent webhook request for this user is already in progress. Retry once it completes.

### 429

Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy.

Body (`application/json`): object

- `error` (string, example: `API token is at rate limit`)

Example shape (generated from the schema; placeholder values, not a real response):

```json
{
  "error": "API token is at rate limit"
}
```
