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

# Rotate a webhook signing secret

> Replace the signing secret of a Streaming Hub webhook subscription, using the overlap in which each delivery carries two signatures.

Replace the signing secret of a webhook subscription without losing a delivery.

## Participants

***

* **Your institution.** Your system calls the Streaming Hub API with an Access Manager token. Your HTTPS endpoint receives the deliveries.
* **Streaming Hub.** The Lerian platform service that signs each delivery. Lerian sets it up for your institution.
* **Lerian product.** The product that publishes the business event, for example Midaz.

## Diagram

***

![Rotate a webhook signing secret](https://mintcdn.com/lerian-49cb71fc/KypD0TIKUCqZ014J/images/en/d2/id-rotate-a-webhook-signing-secret.svg?fit=max\&auto=format\&n=KypD0TIKUCqZ014J\&q=85\&s=25ba919e2b1dcef26ca5c5f3594a9531)

## Steps

***

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Your institution | Streaming Hub | Lerian API | [`POST /v1/subscriptions/{id}/secret/rotate`](https://docs.lerian.studio/en/reference/platform/streaming-hub/rotate-subscription-secret) | Ask for a new signing secret. Send a unique `X-Idempotency` header. |
| 2 | Streaming Hub | Your institution | Response | | The answer has the new `signingSecret` and `overlapUntil`, 24 hours after the rotation. Save the secret now. No read route returns it. |
| 3 | Your institution | Your institution | Internal step | | Add the new secret to your signature check. Keep the previous secret until `overlapUntil`. |
| 4 | Lerian product | Streaming Hub | Event | | The product publishes a business event. |
| 5 | Streaming Hub | Your institution | Webhook | The events in `event_types` | Until `overlapUntil`, each delivery carries two `X-Webhook-Signature` headers. The first uses the new secret and the second uses the previous secret. |
| 6 | Your institution | Streaming Hub | Response | | Accept the delivery when one of the signatures matches a secret that you hold. Answer `2xx`. |
| 7 | Lerian product | Streaming Hub | Event | | After `overlapUntil`, the product publishes another event. |
| 8 | Streaming Hub | Your institution | Webhook | The events in `event_types` | After `overlapUntil`, each delivery carries only the signature of the new secret. |
| 9 | Your institution | Streaming Hub | Response | | Check the signature and answer `2xx`. |
| 10 | Your institution | Your institution | Internal step | | Remove the previous secret from your signature check. |

## How you know it finished

***

[`GET /v1/subscriptions/{id}`](https://docs.lerian.studio/en/reference/platform/streaming-hub/get-subscription) shows `secret_overlap_until` as `null`.

* **The rotate answer is lost.** Send the request again with the same `X-Idempotency` key. When the first request is complete, you get the same secret. While it still runs, you get `409` `idempotency_conflict`. A new key makes another secret.
* **A second rotation.** A second rotation replaces the previous secret at once.

## Related

***

* [Receive events on a webhook](https://docs.lerian.studio/en/diagrams/platform-services/receive-events-on-a-webhook.md)
* [Managing subscriptions](https://docs.lerian.studio/en/platform/streaming-hub/managing-subscriptions.md)
* [Consuming events](https://docs.lerian.studio/en/platform/streaming-hub/consuming-events.md)


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