> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecleff.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payout events

> The four payout.* webhook events: shared core projection, per-event tail fields, and re-fire semantics.

Four `payout.*` events track one Payout through its in-flight lifecycle. They share the
[envelope](/api-reference/webhook-subscriptions#payload-envelope) and the
[ordering contract](/api-reference/webhook-subscriptions#ordering-and-dedup) 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:

```ts theme={null}
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                                                        |

```json theme={null}
{
  "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"
  }
}
```