Event Reference - Formance Documentation

This reference lists the webhook events and JSON payload formats published with Formance Stack v3.2.8. It uses Ledger events v2.0.0, Orchestration events v2.0.0, Payments events v3.0.0, and Reconciliation events v2.4.0 from that release artifact.

Event envelope#

Every delivery uses the same top-level envelope. Webhooks builds the subscription identifier by lowercasing the producer message's app and type fields and joining them with a dot. It also writes that normalized identifier back to the outgoing type field. For example, app: ledger and producer type COMMITTED_TRANSACTIONS become type: ledger.committed_transactions in the webhook body.

The payload object changes with the event type. This example shows a complete Ledger committed-transactions message:

json

{
  "idempotency_key": "order-2026-0042",
  "app": "ledger",
  "version": "v2",
  "date": "2026-08-05T10:30:00Z",
  "type": "ledger.committed_transactions",
  "payload": {
    "ledger": "main",
    "transactions": [
      {
        "postings": [
          {
            "source": "world",
            "destination": "users:001",
            "amount": 1000,
            "asset": "USD/2"
          }
        ],
        "metadata": {
          "order": "ORD-2026-0042"
        },
        "id": 42,
        "timestamp": "2026-08-05T10:30:00Z",
        "reverted": false
      }
    ]
  }
}

Field	Type	Required	Description
`idempotency_key`	string	Yes	Idempotency key supplied by the producing module. The field is present but can be an empty string.
`version`	string	Yes	Version of the module event contract.
`date`	string (`date-time`)	Yes	Time at which the event was published.
`app`	string	Yes	Module that published the event.
`type`	string	Yes	Normalized lowercase `<module>.<event>` identifier shown below.
`payload`	object	Yes	Event-specific data.

The Stack release artifact describes producer envelopes and event payloads. Webhooks normalizes the outgoing envelope as shown above, while the nested payload remains governed by the event's JSON Schema. The tables below summarize its top-level shape. Use the linked v3.2.8 artifact for required payload fields, nested objects, array items, formats, and enum values when generating validators or types.

Ledger events#

Webhook event type	Payload shape
`ledger.committed_transactions`	`ledger`: string; `transactions`: array of objects
`ledger.deleted_metadata`	`ledger`: string; `targetType`: string; `targetId`: string; `key`: string
`ledger.reverted_transaction`	`ledger`: string; `revertedTransaction`: object; `revertTransaction`: object
`ledger.saved_metadata`	`ledger`: string; `targetType`: string; `targetId`: string; `metadata`: object

Orchestration events#

Webhook event type	Payload shape
`orchestration.failed_trigger`	`id`: string; `triggerID`: string; `error`: string
`orchestration.failed_workflow`	`id`: string; `instanceID`: string; `error`: string
`orchestration.failed_workflow_stage`	`id`: string; `instanceID`: string; `number`: integer; `error`: string
`orchestration.started_workflow`	`id`: string; `instanceID`: string
`orchestration.started_workflow_stage`	`id`: string; `instanceID`: string; `number`: integer
`orchestration.succeeded_trigger`	`id`: string; `triggerID`: string
`orchestration.succeeded_workflow`	`id`: string; `instanceID`: string
`orchestration.succeeded_workflow_stage`	`id`: string; `instanceID`: string; `number`: integer

Payments events#

Webhook event type	Payload shape
`payments.connector_reset`	`createdAt`: string; `connectorID`: string
`payments.deleted_pool`	`id`: string; `createdAt`: string
`payments.saved_account`	`id`: string; `provider`: string; `connectorID`: string; `createdAt`: string; `reference`: string; `type`: string; `rawData`: object; `defaultAsset`: string; `name`: string; `metadata`: object
`payments.saved_balance`	`accountID`: string; `connectorID`: string; `provider`: string; `createdAt`: string; `lastUpdatedAt`: string; `asset`: string; `balance`: number
`payments.saved_bank_account`	`id`: string; `createdAt`: string; `name`: string; `accountNumber`: string; `iban`: string; `swiftBicCode`: string; `country`: string; `metadata`: object; `relatedAccounts`: array
`payments.saved_payment`	`id`: string; `connectorID`: string; `provider`: string; `reference`: string; `createdAt`: string; `type`: string; `status`: string; `scheme`: string; `asset`: string; `amount`: number; `initialAmount`: number; account IDs, links, metadata, and raw data
`payments.saved_payment_initiation`	`id`: string; `connectorID`: string; `provider`: string; `reference`: string; `createdAt`: string; `scheduledAt`: string; `description`: string; `type`: string; `amount`: number; `asset`: string; account IDs and metadata
`payments.saved_payment_initiation_adjustment`	`id`: string; `paymentInitiationID`: string; `status`: string; `amount`: number; `asset`: string; `error`: string; `metadata`: object
`payments.saved_payment_initiation_related_payment`	`paymentInitiationID`: string; `paymentID`: string
`payments.saved_pool`	`id`: string; `name`: string; `createdAt`: string; `accountIDs`: array of strings

Reconciliation events#

Webhook event type	Payload shape
`reconciliation.accepted_alert`	`alert`: object; `event`: object
`reconciliation.acknowledged_alert`	`alert`: object; `event`: object
`reconciliation.opened_alert`	`alert`: object; `event`: object
`reconciliation.reopened_alert`	`alert`: object; `event`: object
`reconciliation.resolved_alert`	`alert`: object; `event`: object
`reconciliation.snoozed_alert`	`alert`: object; `event`: object
`reconciliation.unsnoozed_alert`	`alert`: object; `event`: object
`reconciliation.updated_alert`	`alert`: object; `event`: object

The alert object contains the alert state and evidence. The event object records the transition, including its previous and new status, actor metadata, notification decision, and timestamps. Refer to the release artifact for the complete nested schemas and enum values.