Pull events with a cursor - Lerian

Read your events on your own schedule, with no endpoint to expose.

Participants

Your institution. Your system calls the Streaming Hub API with an Access Manager token.
Streaming Hub. The Lerian platform service that keeps your events in arrival order and returns them page by page. Lerian sets it up for your institution.
Lerian product. The product that publishes the business event, for example Midaz.

Diagram

Pull events with a cursor

Steps

#	From	To	Message	Lerian API	What happens
1	Your institution	Streaming Hub	Lerian API	`POST /v1/subscriptions`	Create the subscription with a `name`, `sink_kind` `pull` and the `event_types` you want. Send no endpoint. Send a unique `X-Idempotency` header.
2	Streaming Hub	Your institution	Response		The subscription is `active` at once. A pull subscription needs no ping and has no signing secret.
3	Lerian product	Streaming Hub	Event		The product publishes a business event.
4	Streaming Hub	Streaming Hub	Internal step		Streaming Hub keeps the event and gives it a sequence number, `seq`, in arrival order.
5	Your institution	Streaming Hub	Lerian API	`GET /v1/events`	Read a page with `subscription_id`. The optional `limit` goes from 1 to 500, and the default is 100.
6	Streaming Hub	Streaming Hub	Internal step		Streaming Hub moves the cursor of the subscription to the highest `seq` on the page. The read is the acknowledgment.
7	Streaming Hub	Your institution	Response		The page has the events in `seq` order, each with its `ceId`, and `next_cursor`.
8	Your institution	Your institution	Internal step		Process the events. Ignore a `ceId` that you already processed.
9	Your institution	Streaming Hub	Lerian API	`GET /v1/events`	Read the next page. Send `next_cursor` as `after`, or send no `after` to continue from the cursor.
10	Streaming Hub	Your institution	Response		When the page has fewer events than `limit`, `next_cursor` is `null`.

How you know it finished

A read returns next_cursor null.

Your system stops after a read. The cursor already moved past that page. Read again with after set to the last seq that you processed. That read does not move the cursor back.
The read is refused for rate. The read answers 429 rate_limited. Wait the Retry-After seconds, then read again.