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

# Webhook Events

> HOP webhook event types and delivery payloads

## Event Envelope

Every delivery is an HTTP `POST` whose JSON body follows this envelope:

```json theme={null}
{
  "id": "whn_1234567890abcdefghijklmn",
  "type": "withdraw.completed",
  "created": "2026-07-15T02:00:00Z",
  "attempt": 1,
  "api_version": "2026-07",
  "account_id": "acct_1234567890abcdefghijklmn",
  "data": {
    "id": "po_1234567890abcdefghijklmn",
    "object": "payout",
    "status": "completed"
  }
}
```

| Field         | Type           | Description                                                              |
| ------------- | -------------- | ------------------------------------------------------------------------ |
| `id`          | string         | Unique delivery-event ID. Use it to deduplicate retries.                 |
| `type`        | string         | Subscribed event type.                                                   |
| `created`     | string         | ISO 8601 timestamp when the delivery event was created.                  |
| `attempt`     | integer        | 1-based delivery attempt number.                                         |
| `api_version` | string         | Webhook envelope version. The current value is `2026-07`.                |
| `account_id`  | string or null | Related account external ID, or `null` when there is no account context. |
| `data`        | object         | Current representation of the affected resource.                         |

The request also includes these headers:

| Header                 | Description                                     |
| ---------------------- | ----------------------------------------------- |
| `X-Webhook-Event-ID`   | Same value as the envelope `id`.                |
| `X-Webhook-Event-Type` | Same value as the envelope `type`.              |
| `X-Webhook-Timestamp`  | Unix timestamp used when signing the request.   |
| `X-Webhook-Signature`  | HMAC-SHA256 signature in `sha256=<hex>` format. |
| `X-Webhook-Attempt`    | Same value as the envelope `attempt`.           |

See [Webhook Security](/fx/webhooks/security) before accepting a delivery.

## Supported HOP Events

The `/v1/customers/{customer_id}/webhook-endpoints` API accepts exactly these event types:

| Event                | Trigger                                       | `data` resource                                 |
| -------------------- | --------------------------------------------- | ----------------------------------------------- |
| `deposit.received`   | Funds are credited to an account.             | Payin                                           |
| `deposit.returned`   | A credited deposit is returned.               | Payin                                           |
| `withdraw.created`   | A withdrawal is created.                      | Payout with beneficiary and destination details |
| `withdraw.completed` | A withdrawal completes successfully.          | Payout with beneficiary and destination details |
| `withdraw.failed`    | A withdrawal fails.                           | Payout with beneficiary and destination details |
| `withdraw.cancelled` | A withdrawal is cancelled.                    | Payout with beneficiary and destination details |
| `account.created`    | An account is created.                        | Account                                         |
| `account.updated`    | Account details or verification state change. | Account                                         |

Any other event name is rejected with `422 Unprocessable Entity`.

## Deposit Example

The `data` object for deposit events uses the same payin representation returned by the Payins API. Nullable fields not relevant to this example are omitted for readability.

```json theme={null}
{
  "id": "whn_deposit1234567890abcdefg",
  "type": "deposit.received",
  "created": "2026-07-15T02:00:00Z",
  "attempt": 1,
  "api_version": "2026-07",
  "account_id": "acct_1234567890abcdefghijklmn",
  "data": {
    "id": "pi_1234567890abcdefghijklmn",
    "object": "payin",
    "account_id": "acct_1234567890abcdefghijklmn",
    "amount": "1000.00",
    "currency": "USD",
    "status": "completed",
    "initiated_at": "2026-07-15T01:55:00Z",
    "completed_at": "2026-07-15T02:00:00Z",
    "created": "2026-07-15T01:55:00Z",
    "updated": "2026-07-15T02:00:00Z"
  }
}
```

## Withdrawal Example

The `data` object for withdrawal events contains the payout plus its beneficiary and payout-destination details. Nullable fields not relevant to this example are omitted for readability.

```json theme={null}
{
  "id": "whn_withdraw1234567890abcdef",
  "type": "withdraw.completed",
  "created": "2026-07-15T03:00:00Z",
  "attempt": 1,
  "api_version": "2026-07",
  "account_id": "acct_1234567890abcdefghijklmn",
  "data": {
    "id": "po_1234567890abcdefghijklmn",
    "object": "payout",
    "beneficiary": {
      "id": "bene_1234567890abcdefghijklmn",
      "object": "beneficiary",
      "display_name": "Example Supplier"
    },
    "payout_destination": {
      "id": "dest_1234567890abcdefghijklmn",
      "object": "payout_destination",
      "type": "bank_account",
      "currency": "USD"
    },
    "amount": "250.00",
    "currency": "USD",
    "status": "completed",
    "initiated_at": "2026-07-15T02:45:00Z",
    "completed_at": "2026-07-15T03:00:00Z",
    "created": "2026-07-15T02:45:00Z",
    "updated": "2026-07-15T03:00:00Z"
  }
}
```

## Account Example

Account events carry the current account details and verification state. Detail-only onboarding fields may be `null` in webhook deliveries.

```json theme={null}
{
  "id": "whn_account1234567890abcdefg",
  "type": "account.updated",
  "created": "2026-07-15T04:00:00Z",
  "attempt": 1,
  "api_version": "2026-07",
  "account_id": "acct_1234567890abcdefghijklmn",
  "data": {
    "id": "acct_1234567890abcdefghijklmn",
    "object": "account",
    "customer_id": "cus_1234567890abcdefghijklmn",
    "type": "business",
    "kyc_status": "under_review",
    "display_name": "Acme Pte Ltd",
    "contact_email": "ops@acme.example",
    "country_code": "SG",
    "onboarding": null,
    "requirements": null,
    "associated_persons": null,
    "rejection_reasons": null,
    "created": "2026-07-14T04:00:00Z",
    "updated": "2026-07-15T04:00:00Z"
  }
}
```