# Rotate a webhook signing secret

`POST https://api.cademi.com.br/api/v3/webhooks/{webhook_id}/secret-rotations`

Operation ID: `webhooks.secret_rotations.create` · API v3

Generates a new signing secret for the webhook endpoint.

The previous secret remains valid for `overlap_hours` (24 hours by default, up to 72). During this period, each delivery carries one signature per active secret.

The new secret is returned only once. Retrying the request with the same `Idempotency-Key` does not return the secret again.

Required permissions: `webhooks.rotate_secret`.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `webhook_id` | path | string | yes |  |

## Request body

Content type: `application/json`.

| Field | Type | Required | Description |
|---|---|---|---|
| `overlap_hours` | integer or null | no |  |

## Responses

### 201

Returns the new signing secret. The secret is shown only in this response.

Body: `data`: WebhookSecretRotation.

Fields of WebhookSecretRotation:

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | string, one of `webhook_secret_rotation` | yes |  |
| `previous_secret_expires_at` | string (date-time) | yes |  |
| `secret` | string | yes |  |

### 401

The credential is missing, malformed, expired, or revoked.

Body: Error.

### 403

The current credentials do not have the permission required by this operation.

Body: Error.

### 404

The webhook endpoint was not found or is not accessible with the current credentials.

Body: Error.

### 422

The request body or query parameters failed validation.

Body: ValidationFailed.

Full schema: https://cademi.dev/openapi/v3.json