Rotate a webhook signing secret - Lerian

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

Steps

#	From	To	Message	Lerian API	What happens
1	Your institution	Streaming Hub	Lerian API	`POST /v1/subscriptions/{id}/secret/rotate`	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} 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.