> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwairy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Rotate the signing secret

> Generate a new signing secret for an integration webhook endpoint. For 24 hours deliveries carry two signatures so you can switch without losing events.

Returns a new signing secret, **once**. For 24 hours after the rotation, each
delivery carries two comma-separated signatures in `X-Qwairy-Signature`: the new
one first, then the previous one. Receivers can deploy the new secret without
losing events. See [Verify signatures](https://docs.qwairy.co/developers/integration-webhooks/verify-signatures.md#rotate-the-secret).

Integration webhooks require an active Business, Agency Business or Enterprise plan. Changing an endpoint also requires an API token with write access enabled by an Owner or Manager. See [Integration webhooks](https://docs.qwairy.co/developers/integration-webhooks/overview.md) and [Writing data](https://docs.qwairy.co/developers/writing-data.md).

**Authorization** `string` *required*

Bearer token for your team.

**Idempotency-Key** `string` *required*

Unique key for this operation, at most 255 characters. Completed responses replay for 24 hours.

**webhookId** `string` *required*

Endpoint identifier.

## Response

Returns `200`, the new `ETag` and the endpoint with its new `secret`.
`previousSecretExpiresAt` gives the time when the previous secret stops being
used. The other fields are described in
[List webhook endpoints](https://docs.qwairy.co/developers/endpoints/webhooks/list.md).

## Synthetic request and response

```bash theme={null}
curl -X POST "https://www.qwairy.co/api/v1/webhooks/$WEBHOOK_ID/rotate-secret" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H "Idempotency-Key: webhook-rotate-001"
```

```json theme={null}
{
  "id": "eeeeeeee-0000-4000-8000-000000000000",
  "url": "https://hooks.example.com/qwairy",
  "description": "Production receiver",
  "events": ["run.completed", "run.failed"],
  "brandIds": [],
  "enabled": true,
  "disabledReason": null,
  "failingSince": null,
  "previousSecretExpiresAt": "2026-10-13T10:00:00.000Z",
  "version": 2,
  "createdAt": "2026-10-12T09:00:00.000Z",
  "updatedAt": "2026-10-12T10:00:00.000Z",
  "secret": "synthetic-new-signing-secret"
}
```

## Errors

| Status | Code | Cause |
| - | - | - |
| `404` | `RESOURCE_NOT_FOUND` | The endpoint is missing or belongs to another team |
| `409` | `IDEMPOTENCY_CONFLICT` | The key was reused with a different request |

See [Error codes](https://docs.qwairy.co/developers/errors.md) for authentication, plan, idempotency and server errors. A token without write access returns `403 API_KEY_READ_ONLY`. On `429`, honor `Retry-After`. If the write limiter is unavailable or writes are suspended, the request returns `503 SERVICE_UNAVAILABLE` and nothing changes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.