Skip to main content
Lerian products emit domain events onto a shared streaming backbone. A domain event is a past-tense business fact, for example an account creation or a credential issuance. Any service or downstream subscriber consumes them without coupling to the producer’s internal APIs. This page describes the common transport envelope and platform conventions. The per-product pages are authoritative for each producer’s concrete event types, identifiers, and delivery policy. Streaming Hub delivers these same events to your own infrastructure (webhooks, SQS, RabbitMQ, EventBridge, or pull) with managed retries.

​
Transport

Events travel as CloudEvents 1.0 messages in binary content mode. Binary mode puts the CloudEvents context attributes in transport headers, each prefixed with ce-, 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 publish over Kafka: Midaz, Tracer (in Midaz), Lender, Matcher, and Consignado. Reporter publishes the same envelope over RabbitMQ. It routes each event to a configured exchange with the event key as the routing key. Both transports share the CloudEvents type and versioning conventions. Each producer’s page remains authoritative for exact ids, schemas, destinations, and delivery policy. Tracer’s Kafka producer is the component in Midaz.

​
The envelope

Every record carries these CloudEvents headers.

​
Event type

The v3 contract uses the source-qualified form studio.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, Midaz components/tracer, Matcher, Lender, and Consignado) send their public JSON business facts to:
Commands use 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/tracer facts: lerian.streaming.tracer
  • Matcher facts: lerian.streaming.matcher
  • Lender facts and commands: lerian.streaming.lender and lerian.streaming.lender.commands
  • Consignado gateway facts: lerian.streaming.consignado-gw
Product-internal metering signals are outside this public integration contract and may use separate destinations and encodings. Reporter keeps an explicit RabbitMQ destination: its configured exchange, with the event key as routing key. Its 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, or reporter. All except Matcher pin or validate that exact roster value. 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 in ce-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 introduces a breaking change. On v3 Kafka application streams, the schema version never changes the topic name. A schema bump also leaves explicit RabbitMQ exchanges and routing keys unchanged. An additive change does not affect a consumer that reads payloads as a tolerant reader and ignores unknown fields.

​
Delivery guarantees

Delivery is at-least-once. A consumer commits its position only after it finishes handling a record. A crash mid-handling replays the record rather than dropping it, so 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. By itself it does not prove that the business-state write and outbox insert share one database transaction. Lender and Consignado make that atomic write for their catalog events. Reporter 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. Where the product exposes a streaming manifest, read the manifest at startup.

​
Per-product catalogs

Other Brazil rails also publish events on this contract. Use a rail’s event page or runtime manifest only when the rail explicitly exposes its catalog.