Event structure

Every Fin.com webhook arrives as a POST with the same two top-level keys: an event envelope that identifies the delivery, and a data object that carries the resource the event is about.

{
  "event": { ... },
  "data": { ... }
}

The envelope is identical across all events. The data object differs per event, and its shape matches the schema documented on that event’s API reference page.

Event categories

Webhook events are grouped into the following categories:

customer
transaction
beneficiary
batch.transaction.item
transit.payment

Supported events

Category	Event	Reference
`customer`	`customer.created`	Customer Created
`customer`	`customer.status`	Customer Status
`customer`	`customer.rfi`	Customer RFI
`transaction`	`transaction.status`	Transaction Status
`beneficiary`	`beneficiary.created`	Beneficiary Created
`beneficiary`	`beneficiary.status`	Beneficiary Status
`beneficiary`	`beneficiary.liquidation.deposit`	Beneficiary Liquidation Deposit
`batch.transaction.item`	`batch.transaction.item.status`	Batch Transaction Item Status
`transit.payment`	`transit.payment.status`	Transit Payment Status

The event envelope

Every payload carries the same event object. All five fields are always present.

Field	Type	Description
`id`	`uuid`	Unique identifier for this delivery.
`event_reference_id`	`uuid`	Identifier of the resource the event is about, such as the beneficiary or virtual account ID.
`type`	`string`	The event name, for example `customer.created`.
`created_at`	`date-time`	When the event was generated, in ISO 8601 with microsecond precision.
`sandbox_mode`	`boolean`	`true` when the event originated in sandbox.

{
  "event": {
    "id": "40061557-f125-4b39-97d6-c16a0f1230c1",
    "event_reference_id": "e8fccaeb-fb9d-4fae-846e-ea7c97c70b31",
    "type": "beneficiary.status",
    "created_at": "2026-04-04T17:38:26.843132Z",
    "sandbox_mode": true
  },
  "data": {
    "type": "INDIVIDUAL",
    "active": false,
    "status": "PROCESSING",
    "customer_id": "ecbd3a73-3bcb-40ae-be06-0e71f9b27c2f",
    "beneficiary_id": "e8fccaeb-fb9d-4fae-846e-ea7c97c70b31"
  }
}

The data object

The data object matches the schema on the event’s own reference page. Several events share a schema.

Event	`data` contains
`customer.created`, `customer.status`	Individual or business customer fields, depending on `type`. Individuals carry `first_name`, `last_name`, `country_of_residence`. Businesses carry `business_name`, `country_of_incorporation`, `associated_parties`.
`customer.rfi`	The customer identifier plus the outstanding request for information.
`transaction.status`	Transaction identifier, `status`, and amount details.
`beneficiary.created`, `beneficiary.status`	`beneficiary_id`, `customer_id`, `type`, `active`, `status`.
`beneficiary.liquidation.deposit`	The deposit credited against a beneficiary liquidation address.
`batch.transaction.item.status`	The batch item identifier and its status.
`transit.payment.status`	Payment status, including `retry_attempts`.

Open the reference page for an event to see its full schema and every example payload.

Status values

Events that report a status carry one of a fixed set of values.

Event	Status field	Values
`customer.status` (individual)	`customer_status`	`INCOMPLETE`, `QUEUED`, `PROCESSING`, `REVIEWING`, `APPROVED`, `ON_HOLD`, `IN_COMPLIANCE`, `REINITIATE`, `ACTION_REQUIRED`, `REJECTED`
`customer.status` (business)	`customer_status`	`INCOMPLETE`, `QUEUED`, `PROCESSING`, `REVIEWING`, `APPROVED`, `ASSOCIATED_PARTIES_REMAINING`, `ON_HOLD`, `IN_COMPLIANCE`, `REINITIATE`, `ACTION_REQUIRED`, `REJECTED`
`customer.status` (business)	`associated_parties[].status`	`INITIATED`, `PENDING_REVIEW`, `APPROVED`, `REJECTED`, `ON_HOLD`
`transaction.status`	`status`	`FUNDS_RECEIVED`, `PROCESSING`, `COMPLETED`, `FAILED`, `CANCELLED`
`beneficiary.status`	`status`	`PROCESSING`, `ACTIVE`, `INACTIVE`, `REJECTED`

Verifying deliveries

Every webhook request is signed. See Verifying Webhooks for the HMAC verification steps and code examples.

Responding

Return 200 once you have accepted the delivery.

Get started

Coverage

Onboard your customers

Beneficiaries

Webhooks

Move money

Platform

Event structure

Event categories

Supported events

The event envelope

The data object

Status values

Verifying deliveries

Responding

​Event categories

​Supported events

​The event envelope

​The data object

​Status values

​Verifying deliveries

​Responding

Event categories

Supported events

The event envelope

The data object

Status values

Verifying deliveries

Responding