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

# Event publisher

> Publish transaction events to RabbitMQ in real time so external systems can react without tight coupling to Midaz.

## Why this matters

***

Event publishing lets your systems react to transactions the moment they happen — trigger customer notifications, sync your ERP, feed analytics dashboards, or kick off compliance workflows. All of this without tightly coupling your systems together.

The sections below cover the technical setup. For a business-oriented overview, see [About Midaz](/en/midaz/about-midaz).

## Enabling transaction events

***

To activate this feature, set the following environment variable in the transaction application:

<CodeGroup>
  ```bash JSON theme={null}
  RABBITMQ_TRANSACTION_EVENTS_ENABLED=true
  ```
</CodeGroup>

Once enabled, Midaz starts publishing events to the following exchange in RabbitMQ:

<CodeGroup>
  ```bash JSON theme={null}
  transaction.transaction_events.exchange
  ```
</CodeGroup>

## Event types

***

Midaz emits one of the following event types depending on the transaction lifecycle:

| Action     | Description                                                                                                                             |
| :--------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
| `APPROVED` | The transaction was successfully completed. This includes single-step transactions and two-phase transactions that have been committed. |
| `PENDING`  | A two-phase transaction was created and is waiting for either a commit or cancellation.                                                 |
| `CANCELED` | A two-phase transaction was canceled before confirmation.                                                                               |
| `CREATED`  | A reversal transaction was initiated. This is a transient status that progresses to `APPROVED` once processing completes.               |
| `NOTED`    | An annotation transaction was recorded. The transaction is logged in the ledger without affecting account balances.                     |

## Example event payload

***

<CodeGroup>
  ```json JSON expandable theme={null}
  {
    "source": "midaz",
    "eventType": "transaction",
    "action": "APPROVED",
    "timestamp": "0000-00-00T18:09:03.757330233Z",
    "version": "v3.0.0",
    "organizationId": "0198575d-f9fd-702b-bb15-fa4c980b32c7",
    "ledgerId": "0198575d-fa0b-7ac7-8b7d-9d3ab7dccafc",
    "payload": {
      "id": "0198575f-a8f9-7924-a6d7-8122f2c77ddd",
      "status": {
        "code": "APPROVED",
        "description": "APPROVED"
      },
      "amount": "1",
      "assetCode": "BRL",
      "source": ["account:1"],
      "destination": ["account:2"],
      "metadata": {
        "key": "value"
      },
      "operations": [
        {
          "type": "DEBIT",
          "amount": { "value": "1" },
          "accountAlias": "account:1"
        },
        {
          "type": "CREDIT",
          "amount": { "value": "1" },
          "accountAlias": "account:2"
        }
      ]
    }
  }
  ```
</CodeGroup>

<Note>
  The full payload includes timestamps, balance snapshots, and other identifiers used for auditing and traceability.
</Note>

## Event routing model

***

To ensure flexibility and scalability, Midaz uses a topic exchange to publish messages instead of sending them directly to specific queues. This means you control which events to receive by configuring your own bindings.

### How routing works

Each event published by Midaz is tagged with a routingKey using the format:

```
midaz.transaction.<status>
```

Where `<status>` corresponds to the current transaction status (`APPROVED`, `PENDING`, `CANCELED`, `CREATED`, or `NOTED`).

To consume events, your application must:

<Steps>
  <Step>
    **Create a queue** in RabbitMQ.
  </Step>

  <Step>
    **Bind your queue** to the Midaz exchange using the routingKey pattern that matches your interest.
  </Step>
</Steps>

### Visual overview

<Frame caption="Figure 1. Visual representation of the event routing model.">
  <img src="https://mintcdn.com/lerian-49cb71fc/ZbRj85ZfhOJhCOH6/images/en/docs/event_publisher.jpg?fit=max&auto=format&n=ZbRj85ZfhOJhCOH6&q=85&s=455c8b4e390b0dded93f5fd26b44a35d" alt="" width="1990" height="784" data-path="images/en/docs/event_publisher.jpg" />
</Frame>

<Tip>
  You can configure multiple queues with different bindings to serve specific teams or services independently.
</Tip>

## Queue and binding example

***

### Creating a new queue

<CodeGroup>
  ```json JSON theme={null}
  {
    "queues": [
      {
        "name": "new_queue_name.queue",
        "vhost": "/",
        "durable": true
      }
    ]
  }
  ```
</CodeGroup>

### Binding the queue to receive all events

<CodeGroup>
  ```json JSON theme={null}
  {
    "bindings": [
      {
        "source": "transaction.transaction_events.exchange",
        "vhost": "/",
        "destination": "new_queue_name.queue",
        "destination_type": "queue",
        "routing_key": "midaz.transaction.*"
      }
    ]
  }
  ```
</CodeGroup>

The wildcard `*` matches all five statuses: `APPROVED`, `PENDING`, `CANCELED`, `CREATED`, and `NOTED`. To subscribe to specific events only, replace the wildcard with the exact status — for example, `midaz.transaction.NOTED` to receive only annotation events.

<Note>
  Midaz does not manage or create RabbitMQ queues for you. You are responsible for provisioning queues and setting up the correct bindings.
</Note>