EMISSION_REQUIRED defaults to false. Set EMISSION_REQUIRED=true in a deployment whose downstream systems depend on these events. Bootstrap then fails closed unless event emission is fully wired.
Registered webhooks receive durable control-plane events. The settlement.* and spb.ldl.* families go to the streaming backbone only. Downstream systems read settlement state from settlement.* streaming events and do not poll.
Event families
Ledger integration
Your ledger consumer must receive both the
str.operation.* and settlement.* families on the streaming backbone. The str.operation.accepted event signals dispatch acceptance, not BACEN settlement, so use it to record a pending posting.
Record the final position from the settlement.* facts on the streaming backbone. The business transition behind settlement.settled occurs when the inbound R-leg moves the operation to CONFIRMED. Broker delivery is at-least-once and can redeliver the fact. The ce-id is deterministic, so deduplicate on the (ce-source, ce-id) pair.
The settlement.failed event fires when BACEN rejects the operation or a cancellation reverses a never-settled original. The settlement.returned event fires when a confirmed return reverses a settled original. A return follows the same pattern: str.operation.returnRequested signals the return’s dispatch acceptance, and the parent posting reverses on settlement.returned. Lerian SPB holds no accounting position. The rail carries the message and its settlement state, and your ledger records the money.
Webhooks
Webhook consumers self-register on the canonical event constants. They negotiate payload shapes from a shared event catalog. Delivery is durable. You can retry a failed delivery manually. A dead-letter path handles the deliveries that exhaust their retries.
API conventions
- Auth is a bearer token.
- Writes are idempotent through an idempotency key. A retried submit does not double-dispatch.
- Message-log reads do not expose the signed on-wire frame. You read a single message by its NUOp for structured data. When the rail retained a frame, read its reconstructed XML through the dedicated, separately authorized frame route. It does not separately retain the literal sent bytes.
- Unknown ids return a uniform not-found. The response never reveals whether an operation exists that your institution does not own.