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

# Event structure

> The shape of every Fin.com webhook payload, the events you can subscribe to, and the status values each one carries.

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.

```json theme={null}
{
  "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](/api-reference/webhooks/customer-created)                               |
| `customer`               | `customer.status`                 | [Customer Status](/api-reference/webhooks/customer-status)                                 |
| `customer`               | `customer.rfi`                    | [Customer RFI](/api-reference/webhooks/customer-rfi)                                       |
| `transaction`            | `transaction.status`              | [Transaction Status](/api-reference/webhooks/transaction-status)                           |
| `beneficiary`            | `beneficiary.created`             | [Beneficiary Created](/api-reference/webhooks/beneficiary-created)                         |
| `beneficiary`            | `beneficiary.status`              | [Beneficiary Status](/api-reference/webhooks/beneficiary-status)                           |
| `beneficiary`            | `beneficiary.liquidation.deposit` | [Beneficiary Liquidation Deposit](/api-reference/webhooks/beneficiary-liquidation-deposit) |
| `batch.transaction.item` | `batch.transaction.item.status`   | [Batch Transaction Item Status](/api-reference/webhooks/batch-transaction-item-status)     |
| `transit.payment`        | `transit.payment.status`          | [Transit Payment Status](/api-reference/webhooks/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.                                                  |

```json theme={null}
{
  "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](/guides/webhooks/verifying-webhooks) for the HMAC verification steps and code examples.

## Responding

Return `200` once you have accepted the delivery.