> ## 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.

# Receive events on a webhook

> Subscribe an HTTPS endpoint in Streaming Hub, activate it with a signed test event, and receive the signed business events of Lerian products.

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

***

![Receive events on a webhook](https://mintcdn.com/lerian-49cb71fc/KypD0TIKUCqZ014J/images/en/d2/id-receive-events-on-a-webhook.svg?fit=max\&auto=format\&n=KypD0TIKUCqZ014J\&q=85\&s=a68d1af70181087693f10375421b6488)

## Steps

***

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Your institution | Streaming Hub | Lerian API | [`GET /v1/catalog`](https://docs.lerian.studio/en/reference/platform/streaming-hub/get-event-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`](https://docs.lerian.studio/en/reference/platform/streaming-hub/create-subscription) | 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`](https://docs.lerian.studio/en/reference/platform/streaming-hub/ping-subscription) | 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}`](https://docs.lerian.studio/en/reference/platform/streaming-hub/get-subscription) 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.

## Related

***

* [Rotate a webhook signing secret](https://docs.lerian.studio/en/diagrams/platform-services/rotate-a-webhook-signing-secret.md)
* [Recover a failing webhook](https://docs.lerian.studio/en/diagrams/platform-services/recover-a-failing-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)
* [Streaming Hub errors](https://docs.lerian.studio/en/reference/platform/streaming-hub/streaming-hub-error-list.md)


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