Transport
Events travel as CloudEvents 1.0 messages in binary content mode. Binary mode puts the CloudEvents context attributes in transport headers, each prefixed withce-, and the event body in the message value as JSON. A consumer reads routing and identity from the headers without deserializing the payload.
Most producers — Midaz, Midaz components/tracer, Lender, Matcher, Consignado — publish over Kafka. Two publish the same envelope over RabbitMQ: Reporter routes each event to a configured exchange with the event key as the routing key, and Fetcher does the same for its job terminal events. The CloudEvents type and versioning conventions are shared across both transports; each producer’s page remains authoritative for exact ids, schemas, destinations, and delivery policy. The standalone LerianStudio/tracer-pre-dev repository currently has no external streaming and is not this producer.
The envelope
Every record carries these CloudEvents headers.Event type
The v3 contract uses the source-qualified formstudio.lerian.<source>.<resource>.<event>. The same <source> value appears in ce-source; ce-resourcetype and ce-eventtype carry the dispatch key as separate headers. Producers still pinned to lib-streaming v2 use the source-free form studio.lerian.<resource>.<event>; check the producer-specific page or manifest before routing.
Topic naming
Kafka producers on the v3 application-stream contract — including Midaz, Midazcomponents/tracer, Matcher, Lender, and Consignado — send their public JSON business facts to:
lerian.streaming.<ce-source>.commands; the producer’s dead letters use lerian.streaming.<ce-source>.dlq. There is no separate .commands.dlq topic. Resource type, event type, and schema version stay in CloudEvents headers, so schema-major changes do not rename the topic.
Examples:
- Midaz ledger, CRM, and Fees public JSON facts:
lerian.streaming.ledger - Midaz
components/tracerfacts:lerian.streaming.tracer - Matcher facts:
lerian.streaming.matcher - Lender facts and commands:
lerian.streaming.lenderandlerian.streaming.lender.commands - Consignado gateway facts:
lerian.streaming.consignado-gw
RABBITMQ_JOB_EVENTS_EXCHANGE with job.completed or job.failed. Their ce-type values are still source-qualified.
Source
ce-source identifies the producing service and is part of the wire contract. Current v3 product examples use ledger, tracer (Midaz components/tracer), matcher, lender, consignado-gw, fetcher, or reporter; all except Matcher pin or validate that exact roster value, while Matcher derives its wire identity from the configured value. v3 Kafka producers embed the source in the application topic and all v3 producers embed it in ce-type. Changing it therefore changes consumer routing and identity; treat it as a breaking change.
Subject and tenant
ce-subject carries the id of the aggregate the event is about — the account, transaction, or credential the fact concerns. ce-tenantid carries the owning tenant. Its single-tenant behavior is producer-specific: Midaz always sends literal default in single-tenant or tenantless scope, while other producers document their own behavior. Follow the producer-specific contract.
Schema versioning
Each event declares its own payload schema version ince-schemaversion, independent of other events from the same source. The default is 1.0.0. A minor bump is additive and backward compatible; a major bump is a breaking change. On v3 Kafka application streams, the schema version never changes the topic name. Explicit RabbitMQ exchanges and routing keys are also unchanged by a schema bump. A consumer that reads payloads as a tolerant reader, ignoring unknown fields, is unaffected by an additive change.
Delivery guarantees
Delivery is at-least-once. A consumer commits its position only after it finishes handling a record, so a crash mid-handling replays the record rather than dropping it — which means the same event can arrive more than once. Deduplicate on the(ce-source, ce-id) pair (CloudEvents defines event identity by that combination, and ce-id alone can collide across sources) and keep handlers idempotent.
On the producer side, the delivery policy belongs to each event definition, not to the platform. An outbox-backed policy guarantees durable relay and retry, but it does not by itself prove that the business-state write and outbox insert share one database transaction. Lender and Consignado make that atomic write for their catalog events. Fetcher persists the terminal state with a pending marker, then inserts the event into its durable Mongo outbox in a separate operation; a repair loop re-emits the stable ce-id until the marker clears. Reporter also emits after the state commit, and its critical policies then use a durable Mongo outbox in a separate operation. A crash or a failed outbox insert in that post-commit window loses the Reporter event: no reconciliation recovers it, and only an error log and a metric record the loss. Matcher and Reporter also publish operational signals directly with outbox fallback. Check the product’s own event page for both its policy and transaction boundary, and where the product exposes a streaming manifest, read the manifest at startup.
Per-product catalogs
The Brazil rails (STA, CCS, SLC, SPB, SPI, SILOC, SISBAJUD, bank transfer, and the Pix services) also publish events on this same contract; see each rail’s own documentation area for its catalog.