Event publisher

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.

Enabling transaction events

Transaction event publication is enabled by default — Midaz treats the flag as enabled unless it is explicitly set to false. The bundled example configuration ships it set to false, so on a stack started from that example, make sure the flag is not set to false (or set it to true) in the transaction application:

RABBITMQ_TRANSACTION_EVENTS_ENABLED=true

With the flag left enabled, Midaz publishes 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.
`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

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

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

Midaz event routing model, showing how published events reach subscriber queues bound to the exchange by routing-key patterns — Figure 1. Visual representation of the event routing model.

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.*"
    }
  ]
}

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.

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

Midaz Core

CRM

Fees

Event publisher

Why this matters

Enabling transaction events

Event types

Example event payload

Event routing model

How routing works

Visual overview

Queue and binding example

Creating a new queue

Binding the queue to receive all events

​Why this matters

​Enabling transaction events

​Event types

​Example event payload

​Event routing model

​How routing works

​Visual overview

​Queue and binding example

​Creating a new queue

​Binding the queue to receive all events

Why this matters

Enabling transaction events

Event types

Example event payload

Event routing model

How routing works

Visual overview

Queue and binding example

Creating a new queue

Binding the queue to receive all events