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

# Receiving Midaz events

> Consume Midaz events from Kafka, understand the legacy RabbitMQ surface, and check the current Streaming Hub compatibility boundary.

Midaz emits CloudEvents for ledger, CRM, Fees, and Tracer business facts. The current public integration contract is the **Kafka/lib-streaming** surface. The former internal billing stream is retired. Legacy RabbitMQ exchanges remain outside the public catalog.

## Current event surface: Kafka

***

Enable publication on each producing service:

```env theme={null}
STREAMING_ENABLED=true
STREAMING_BROKERS=<broker-list>
STREAMING_CLOUDEVENTS_SOURCE=ledger
```

Set `STREAMING_CLOUDEVENTS_SOURCE` when you enable streaming. Use `ledger` for the ledger, CRM, and Fees binary. Use `tracer` for Tracer. Each service rejects any other value at startup.

Midaz uses one v3 application fact topic per producing service:

* Ledger, CRM, and Fees: `lerian.streaming.ledger`
* Tracer: `lerian.streaming.tracer`

Examples:

* `organization.created` rides `lerian.streaming.ledger`
* `transaction.posted` rides `lerian.streaming.ledger`
* `fee_charge.applied` rides `lerian.streaming.ledger`
* `rule.created` rides `lerian.streaming.tracer`

The CloudEvents type is source-qualified as `studio.lerian.<source>.<resource>.<event>`. Headers `ce-resourcetype` and `ce-eventtype` carry the dispatch key separately. The `ce-tenantid` header is always present for Midaz. It carries the resolved tenant ID in multi-tenant scope, and the literal `default` in single-tenant or tenantless scope. Payload schema is `1.0.0` for the current catalog.

The ledger and Tracer each serve their public JSON business-event catalog and topic mapping at:

```http theme={null}
GET /v1/streaming/manifest
```

The manifest route remains available even when you disable publication. Use it as the deployment-time contract instead of guessing topics. The [Midaz event reference](/en/reference/events/midaz) and [Tracer event reference](/en/reference/events/tracer) list every public business event and payload.

### Delivery semantics

Midaz publishes these business events directly after the state change. It does not persist them in a streaming outbox. Midaz logs publication failures and does not return them to the business command. Consumers must still be idempotent and deduplicate on `(ce-source, ce-id)` because broker delivery can repeat a published record. Money values use decimal strings. Never parse them as binary floating point.

### Consumer checklist

1. Read the producer manifest.
2. Subscribe to the producer's application topic.
3. Route on `ce-resourcetype` and `ce-eventtype`, not on payload shape.
4. Validate `ce-schemaversion` before decoding.
5. Persist your deduplication key before acknowledging the record.

## Legacy RabbitMQ surface

***

Midaz also maintains legacy RabbitMQ exchanges for selected overdraft and audit events. This is not the complete lib-streaming catalog.

The bundled example configuration ships these outbound exchanges disabled. If you enable them, you own queue bindings, `ack`/`nack`, dead-lettering, retries, and consumer isolation. The internal async transaction balance-operation pipeline controlled by `RABBITMQ_TRANSACTION_ASYNC` is not a public event feed.

Use the Kafka surface for new integrations unless you explicitly depend on a legacy RabbitMQ contract.

## Streaming Hub compatibility

***

Streaming Hub follows the v3 Midaz application topics `lerian.streaming.ledger` and `lerian.streaming.tracer`. A subscription can therefore receive Midaz facts when you enable the producer, hub ingest, and destination runtime. Match on the event key from `ce-resourcetype` and `ce-eventtype`. Do not expect a per-event Kafka topic.

## Decision

***

| Need                                                          | Use                                       |
| ------------------------------------------------------------- | ----------------------------------------- |
| Public Midaz business-event catalog                           | Direct Kafka consumption or Streaming Hub |
| Existing compatibility integration on selected exchanges      | Legacy RabbitMQ                           |
| Managed webhook, pull, SQS, RabbitMQ, or EventBridge delivery | Streaming Hub subscription                |