Receive events on a webhook

Receive the business events of Lerian products at your own HTTPS endpoint, each one signed by Streaming Hub.

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 matches each event to your subscriptions and delivers it. Lerian sets it up for your institution.
Lerian product. The product that publishes the business event, for example Midaz.

Diagram

Steps

#	From	To	Message	Lerian API	What happens
1	Your institution	Streaming Hub	Lerian API	`GET /v1/catalog`	Read the events that you can subscribe to.
2	Streaming Hub	Your institution	Response		The catalog gives each event its `eventKey`. Put that value in `event_types` exactly as the catalog gives it.
3	Your institution	Streaming Hub	Lerian API	`POST /v1/subscriptions`	Create the subscription with a `name`, `sink_kind` `webhook`, your `https://` endpoint and the `event_types` you want. Send a unique `X-Idempotency` header.
4	Streaming Hub	Your institution	Response		The answer has the subscription in `pending_verification` and the `signingSecret`. Save the secret now. No read route returns it.
5	Your institution	Streaming Hub	Lerian API	`POST /v1/subscriptions/{id}/ping`	Ask Streaming Hub to test your endpoint.
6	Streaming Hub	Your institution	Webhook	Event `hub.subscription.verification_ping`	Streaming Hub sends a signed test event to your endpoint.
7	Your institution	Streaming Hub	Response		Your endpoint checks the signature with the secret and answers `2xx`.
8	Streaming Hub	Your institution	Response		The ping answers `outcome` `ok`. The subscription is now `active`.
9	Lerian product	Streaming Hub	Event		The product publishes a business event.
10	Streaming Hub	Streaming Hub	Internal step		Streaming Hub matches the event to your active subscriptions that ask for it.
11	Streaming Hub	Your institution	Webhook	The events in `event_types`	Streaming Hub sends the event to your endpoint, signed with your secret.
12	Your institution	Streaming Hub	Response		Your endpoint checks the signature and answers `2xx`. It ignores an `X-Lerian-Event-Id` that it already processed.

How you know it finished

The ping answers outcome ok, and GET /v1/subscriptions/{id} shows verification_state active and enabled true.

The ping fails. The ping answers outcome failed with a detail, and the subscription stays in pending_verification. Fix the endpoint and ping again.
The create is refused. By default, Streaming Hub refuses an endpoint at a private, loopback or metadata address, or with credentials in the URL, with 422 endpoint_blocked. A name that is in use gets 409 subscription_name_taken.
The same event arrives again. Only a 2xx answer counts as delivered. Streaming Hub retries any other answer, so one event can arrive more than once.

​Participants

​Diagram

​Steps

​How you know it finished

​Related

Participants

Diagram

Steps

How you know it finished

Related