> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://docs.prividium.com/api/mcp` to find what you need.
>
> **Have feedback?** Use `submit_feedback` on the same MCP server.

Rotate immediately if a signing key is exposed or suspected compromised.

:::info[All webhook management routes require authentication.]
:::

## 1. Rotate from the Admin Dashboard

You can rotate signing keys directly from the webhook details page in the admin UI.

1. Open **Webhooks**.
2. Select the webhook row to open its details page.
3. Select **Rotate Signing Key**.
4. Enter `retire_after_secs`.
   * The field is required in the UI.
   * The default value is `86400`.
5. Select **Rotate**.
6. In the confirmation dialog, type `Rotate signing key`.
7. Confirm the rotation.
8. Copy the new signing key from the one-time modal.
9. Acknowledge the modal to finish the flow.

:::info[The rotated signing key is returned once.]
If you do not copy it during the one-time modal, you must rotate again.
:::

## 2. Obtain Endpoint UUID for Direct API Use

Use list endpoints to find `endpoint.id` for the webhook you want to rotate. Or open the webhook details page in the
admin UI and copy the webhook ID.

Address webhook list:

```bash
curl "http://localhost:8000/api/v1/address-webhook?limit=20&offset=0" \
  -H "Authorization: Bearer <TOKEN>"
```

Event webhook list:

```bash
curl "http://localhost:8000/api/v1/event-webhook?limit=20&offset=0" \
  -H "Authorization: Bearer <TOKEN>"
```

Use `endpoint.id` as `<ENDPOINT_UUID>`.

## 3. Rotate Signing Key with the API

Rotate event webhook signing key:

```bash
curl -X POST "http://localhost:8000/api/v1/event-webhook/<ENDPOINT_UUID>/signing-keys/rotate" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "retire_after_secs": 86400,
    "version": "v1"
  }'
```

Rotate address webhook signing key:

```bash
curl -X POST "http://localhost:8000/api/v1/address-webhook/<ENDPOINT_UUID>/signing-keys/rotate" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "retire_after_secs": 86400,
    "version": "v1"
  }'
```

## 4. Rotation Parameters

Direct API requests currently support these fields:

* `retire_after_secs`: overlap window where old and new keys are valid. `86400` seconds is a practical default.
* `version`: signature version. Current value is `v1`.

The admin dashboard exposes only `retire_after_secs`. It does not let you configure `version`.

API requests can omit both fields:

```json
{}
```

## 5. Rotation Response

The response includes:

* `signing_key`
* `key_id`
* `version`

:::info[The signing key is returned once.]
:::

## 6. Multi-Signature Overlap

During the rotation overlap window, deliveries can include more than one signature:

```text
webhook-signature: v1,<sig1> v1,<sig2>
```

Consumers should:

1. Parse all provided signatures.
2. Attempt verification with all active keys.
3. Accept the request if any signature validates.

See [Verifying Signatures](/developers/webhooks/verifying-signatures) for the verification details.

## 7. Recommended Workflow

1. Rotate and securely store the new signing key.
2. Deploy verifier changes to accept both old and new keys.
3. Wait for the overlap window to pass.
4. Remove the old key from your verifier.

## Common Pitfalls

* Rotating but not storing the newly returned key.
* Keeping only one active key in verification during overlap.
* Removing the old key before `retire_after_secs` has elapsed.

## Related

* [Using Webhooks in the UI](/developers/webhooks/using-webhooks-in-the-ui)
* [Verifying Signatures](/developers/webhooks/verifying-signatures)
* [Webhook Delivery Handling](/developers/webhooks/webhook-delivery-handling)