_Docs/
Get StartedModulesPlatformDeployCookbookChangelogReference
_Stack
_Modules
  • Ledger
    • Quick Start
    • Core Concepts
      • Accounts
      • Transactions
      • Constraints
      • Source/destination
      • Designing a Chart of Accounts
    • Working with the Ledger
      • Assets & Currency conversion
      • Bi-temporality
      • Bulk processing
      • Filtering queries
      • Idempotency
      • Data isolation with buckets
      • From credit/debit to source/destination
      • Streaming to analytics systems
      • Ledger Schema
    • Advanced Topics
      • Architecting for scale
      • Events Publishers
      • Performance model
  • Numscript
  • Connectivity
  • WalletsEE
  • FlowsEE
  • ReconciliationEE
  1. Modules
  3. Ledger
  5. Advanced Topics
  7. Events Publishers
Ledger

Events Publishers

Events#

The following event types are available:

EventDescription
SET_METADATALog entry for setting metadata on an account or transaction
NEW_TRANSACTIONLog entry for creating a new transaction with associated account metadata
REVERTED_TRANSACTIONLog entry for reverting an existing transaction
DELETE_METADATALog entry for deleting metadata from an account or transaction
INSERTED_SCHEMALog entry for inserting a new ledger schema
COMMITTED_TRANSACTIONSExternal event published when transactions are committed to the ledger
SAVED_METADATAExternal event published when metadata is saved on an entity
DELETED_METADATAExternal event published when metadata is deleted from an entity

Publishing to HTTP#

An HTTP publisher is available out of the box since 1.3.x. It allows you to push ledger events to an http server of your choice, in a webhook-like fashion. It can be enabled by setting the configuration variables PUBLISHER_HTTP_ENABLED and PUBLISHER_TOPIC_MAPPING.

For HTTP publishing on Formance Cloud, please refer instead to the webhooks section of The Formance Platform.

The event payload is formatted as follows:

A COMMITTED_TRANSACTIONS event published when new transactions are committed to a ledger. Contains the complete transaction data including postings, volumes, and associated account metadata.

JSON
{
  "date": "2024-01-15T10:30:00Z",
  "app": "ledger",
  "version": "v2",
  "type": "COMMITTED_TRANSACTIONS",
  "payload": {
    "ledger": "quickstart",
    "transactions": [
      {
        "id": 1,
        "postings": [
          {
            "source": "world",
            "destination": "users:001",
            "amount": "100",
            "asset": "USD"
          },
          {
            "source": "users:001",
            "destination": "payments:001",
            "amount": "100",
            "asset": "USD"
          }
        ],
        "metadata": {
          "category": "payment",
          "reference": "tx_001"
        },
        "timestamp": "2024-01-15T10:30:00Z",
        "insertedAt": "2024-01-15T10:30:01Z",
        "updatedAt": "2024-01-15T10:30:01Z",
        "reference": "payment_001",
        "postCommitVolumes": {
          "users:001": {
            "USD": {
              "input": "100",
              "output": "100",
              "balance": "0"
            }
          },
          "payments:001": {
            "USD": {
              "input": "100",
              "output": "0",
              "balance": "100"
            }
          },
          "world": {
            "USD": {
              "input": "0",
              "output": "100",
              "balance": "-100"
            }
          }
        },
        "preCommitVolumes": {
          "users:001": {
            "USD": {
              "input": "0",
              "output": "0",
              "balance": "0"
            }
          },
          "payments:001": {
            "USD": {
              "input": "0",
              "output": "0",
              "balance": "0"
            }
          },
          "world": {
            "USD": {
              "input": "0",
              "output": "0",
              "balance": "0"
            }
          }
        },
        "reverted": false
      }
    ],
    "accountMetadata": {
      "users:001": {
        "name": "John Doe",
        "email": "john@example.com"
      },
      "payments:001": {
        "type": "payment_processor",
        "provider": "stripe"
      }
    }
  }
}

Publishing to Kafka#

An integration with Kafka is available out of the box since 1.3.x. It allows you to push ledger events to a kafka broker of your choice, bringing easy and reliable extensibility. It can be enabled by setting the configuration variables PUBLISHER_KAFKA_ENABLED, PUBLISHER_KAFKA_BROKER and PUBLISHER_TOPIC_MAPPING.

Other variables are available for further authentication and configuration.

Access to Kafka publishing is not yet available in Formance Cloud.

The event payload format is the same as for HTTP publishing:

A COMMITTED_TRANSACTIONS event published when new transactions are committed to a ledger. Contains the complete transaction data including postings, volumes, and associated account metadata.

JSON
{
  "date": "2024-01-15T10:30:00Z",
  "app": "ledger",
  "version": "v2",
  "type": "COMMITTED_TRANSACTIONS",
  "payload": {
    "ledger": "quickstart",
    "transactions": [
      {
        "id": 1,
        "postings": [
          {
            "source": "world",
            "destination": "users:001",
            "amount": "100",
            "asset": "USD"
          },
          {
            "source": "users:001",
            "destination": "payments:001",
            "amount": "100",
            "asset": "USD"
          }
        ],
        "metadata": {
          "category": "payment",
          "reference": "tx_001"
        },
        "timestamp": "2024-01-15T10:30:00Z",
        "insertedAt": "2024-01-15T10:30:01Z",
        "updatedAt": "2024-01-15T10:30:01Z",
        "reference": "payment_001",
        "postCommitVolumes": {
          "users:001": {
            "USD": {
              "input": "100",
              "output": "100",
              "balance": "0"
            }
          },
          "payments:001": {
            "USD": {
              "input": "100",
              "output": "0",
              "balance": "100"
            }
          },
          "world": {
            "USD": {
              "input": "0",
              "output": "100",
              "balance": "-100"
            }
          }
        },
        "preCommitVolumes": {
          "users:001": {
            "USD": {
              "input": "0",
              "output": "0",
              "balance": "0"
            }
          },
          "payments:001": {
            "USD": {
              "input": "0",
              "output": "0",
              "balance": "0"
            }
          },
          "world": {
            "USD": {
              "input": "0",
              "output": "0",
              "balance": "0"
            }
          }
        },
        "reverted": false
      }
    ],
    "accountMetadata": {
      "users:001": {
        "name": "John Doe",
        "email": "john@example.com"
      },
      "payments:001": {
        "type": "payment_processor",
        "provider": "stripe"
      }
    }
  }
}
Architecting for scalePerformance model
On This Page
  • Events
  • Publishing to HTTP
  • Publishing to Kafka