Beneficiary events

Three beneficiary.* events report how a Beneficiary, or one of their bank accounts, fared at registration. Webhooks lists when each one is sent.

Agents: fetch this page as plain markdown at https://docs.usecleff.com/api-reference/webhook-events-beneficiary.md.

`beneficiary.details_submitted`

Field	Type	Meaning
`beneficiary_id`	`string`	Cleff Beneficiary identifier
`status`	`string`	Always `"details_submitted"`

{
  "id": "evt_…",
  "type": "beneficiary.details_submitted",
  "api_version": "2026-05-27",
  "occurred_at": "2026-05-26T12:20:32.000Z",
  "created_at": "2026-05-26T12:20:33.000Z",
  "sequence": 10473,
  "data": {
    "beneficiary_id": "c2a7e4d9-1b3f-4e8a-9d6c-7f5b0a2e8c14",
    "status": "details_submitted"
  }
}

`beneficiary.bank_account.registered`

Field	Type	Meaning
`bank_account_id`	`string`	Cleff bank-account identifier; the same id Payouts name
`beneficiary_id`	`string`	Cleff Beneficiary identifier the account belongs to
`last4`	`string`	Masked display value — trailing 4 of the IBAN or account number; a Pix key masks by key type
`country`	`string`	ISO 3166-1 alpha-2 country of the account
`currency`	`string`	ISO 4217 code the account is denominated in

{
  "id": "evt_…",
  "type": "beneficiary.bank_account.registered",
  "api_version": "2026-05-27",
  "occurred_at": "2026-05-26T12:20:32.000Z",
  "created_at": "2026-05-26T12:20:33.000Z",
  "sequence": 10474,
  "data": {
    "bank_account_id": "9a04b6f2-5c1e-4d7a-8b3f-2e6c9d0a1f57",
    "beneficiary_id": "c2a7e4d9-1b3f-4e8a-9d6c-7f5b0a2e8c14",
    "last4": "6789",
    "country": "US",
    "currency": "USD"
  }
}

`beneficiary.enrollment_rejected`

Field	Type	Meaning
`beneficiary_id`	`string`	Cleff Beneficiary identifier
`bank_account_id`	`string \| null`	The refused account; `null` when the refusal named no specific account
`status`	`string`	Always `"enrollment_rejected"`
`failure_detail`	`string`	Human-readable reason the rail gave for refusing

{
  "id": "evt_…",
  "type": "beneficiary.enrollment_rejected",
  "api_version": "2026-05-27",
  "occurred_at": "2026-05-26T12:20:32.000Z",
  "created_at": "2026-05-26T12:20:33.000Z",
  "sequence": 10475,
  "data": {
    "beneficiary_id": "c2a7e4d9-1b3f-4e8a-9d6c-7f5b0a2e8c14",
    "bank_account_id": "9a04b6f2-5c1e-4d7a-8b3f-2e6c9d0a1f57",
    "status": "enrollment_rejected",
    "failure_detail": "400 invalid routing number"
  }
}

​beneficiary.details_submitted

​beneficiary.bank_account.registered

​beneficiary.enrollment_rejected

`beneficiary.details_submitted`

`beneficiary.bank_account.registered`

`beneficiary.enrollment_rejected`