Payout events

Four payout.* events track one Payout through its in-flight lifecycle. They share the envelope and the ordering contract every Cleff webhook uses; subscribe to them by name in enabled_events.

Shared core

All four carry a shared core projection plus an event-specific tail:

type Core = {
  payout_id: string; // Cleff Payout identifier
  external_ref: string | null; // Business-supplied reference (e.g. trade/invoice ID)
  beneficiary_id: string; // Cleff Beneficiary identifier
  amount: string; // Decimal string in major units, e.g. "123.45" (ISO 4217 exponent applied)
  currency: string; // ISO 4217 code, e.g. "USD"
  rail_ref: string | null; // Provider reference for the disbursement, once returned
};

rail_ref is the provider’s opaque reference for the disbursement and is null until the provider returns one, typically populated by payout.disbursed, sometimes earlier. Cleff’s relationship with the upstream provider is internal: subscribers never see the provider name, the provider’s payout ID, or the provider’s raw lifecycle strings. Lifecycle position is conveyed by type.

The events

Type	Fires when	Tail fields	Re-fire semantics
`payout.disbursement_submitted`	Cleff hands the disbursement to the upstream provider	`status: "disbursement_submitted"`	Once per Payout
`payout.acknowledged`	First authenticated provider webhook arrives for the attempt	`acknowledged_at: string` (ISO-8601)	Once per attempt
`payout.estimated_arrival_at`	Provider supplies (or refines) an ETA for funds delivery	`expected_delivery_date: string` (ISO-8601)	Re-fires only when the ETA value changes; same-ETA replays are dropped
`payout.disbursed`	Provider confirmed the Payout has left Cleff	`status: "disbursed"`	Once per Payout

{
  "id": "evt_…",
  "type": "payout.disbursed",
  "api_version": "2026-05-27",
  "occurred_at": "2026-05-26T12:20:32.000Z",
  "created_at": "2026-05-26T12:20:33.000Z",
  "sequence": 10472,
  "data": {
    "payout_id": "po_…",
    "external_ref": "INVOICE-2026-0001",
    "beneficiary_id": "ben_…",
    "amount": "123.45",
    "currency": "USD",
    "rail_ref": "FAKE-ACH-2026-0001",
    "status": "disbursed"
  }
}

Basics

Reference

Shared core

The events

​Shared core

​The events

Shared core

The events