Event publisher

Midaz introduces real-time event publishing for transactional updates. When enabled, every processed transaction emits an event to a dedicated RabbitMQ exchange. This allows external applications to listen to these events and consume them through custom queues, without creating tight dependencies.

Enabling transaction events

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

RABBITMQ_TRANSACTION_EVENTS_ENABLED=true

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

transaction.transaction_events.exchange

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.

Example event payload

{
  "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"
      }
    ]
  }
}

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

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, or CANCELED).

To consume events, your application must:

Create a queue in RabbitMQ.
Bind your queue to the Midaz exchange using the routingKey pattern that matches your interest.

Visual overview

Figure 1. Visual representation of the event routing model.

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

Queue and binding example

Creating a new queue

{
  "queues": [
    {
      "name": "new_queue_name.queue",
      "vhost": "/",
      "durable": true
    }
  ]
}

Binding the queue to receive all events

{
  "bindings": [
    {
      "source": "transaction.transaction_events.exchange",
      "vhost": "/",
      "destination": "new_queue_name.queue",
      "destination_type": "queue",
      "routing_key": "midaz.transaction.*"
    }
  ]
}

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