> ## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.