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

# Integrating with Lerian SPB

> The event families, Midaz ledger touchpoint, webhook delivery, and API conventions for building on Lerian SPB.

Lerian SPB is event-driven. Every operation and lifecycle change emits a domain event, delivered both to registered webhooks and to the platform's streaming backbone, so downstream systems react to settlement state without polling.

## Event families

***

| Family                  | Emitted on                                                                                             |
| ----------------------- | ------------------------------------------------------------------------------------------------------ |
| `str.operation.*`       | Operation lifecycle — `accepted`, `received`, `confirmed`, `sent`, `submitted`, `observed`, `progress` |
| `str.readiness.changed` | The rail's readiness state changes                                                                     |
| `str.certificate.*`     | Signing certificate `rotated` or `expiring`                                                            |
| `str.approval.*`        | A queued emission is `signed` or `denied`                                                              |
| `str.reconciliation.*`  | A reconciliation case is `opened` or `resolved`                                                        |
| `str.schedule.changed`  | The operating-window grades change                                                                     |
| `str.message.*`         | Message-level `received`, `sent`, `submitted`, `failed`, `rejected`                                    |

## Midaz touchpoint

***

The Midaz ledger plugin subscribes to the `str.operation.*` family and keys its ledger postings on it — `str.operation.accepted` is the posting trigger. Lerian SPB holds **no** accounting position; the position lives entirely in Midaz. The rail carries the message and its settlement state, and Midaz records the money.

## Inbound from BACEN

***

Lerian SPB consumes the inbound STR settlement replies (R-legs) and the GEN-family notices from BACEN over the RSFN. A submitted operation stays open until its R-leg arrives and moves it to `SETTLED` or `REJECTED`, with BACEN's settlement fields projected verbatim.

## Webhooks

***

Webhook consumers self-register on the canonical event constants and negotiate payload shapes from a shared event catalog. Delivery is durable: a failed delivery can be retried manually, and a dead-letter path handles deliveries that exhaust their retries.

## API conventions

***

* **Auth** is a bearer token.
* **Writes are idempotent** via an idempotency key, so a retried submit does not double-dispatch.
* **Reads never leak raw protocol payloads.** A single message can be read by its NUOp, with an XML view reconstructed on read; the literal sent bytes are not separately retained.
* **Unknown ids return a uniform not-found**, which never reveals whether an operation your institution does not own exists.