Webhook Events

Event Envelope

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

{
  "id": "whn_1234567890abcdefghijklmn",
  "type": "payout.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 before accepting a delivery.

Supported HOP Events

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

Event	Trigger	`data` resource
`payin.received`	Funds are credited to an account.	Payin
`payin.returned`	A credited payin is returned.	Payin
`payout.created`	A payout is created.	Payout with beneficiary and destination details
`payout.completed`	A payout completes successfully.	Payout with beneficiary and destination details
`payout.failed`	A payout fails or is cancelled before release — `data.status` carries the precise state (`failed` or `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.

Payin Example

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

{
  "id": "whn_payin12345678900abcdefg",
  "type": "payin.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"
  }
}

Payout Example

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

{
  "id": "whn_payout1234567890abcdef",
  "type": "payout.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.

{
  "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"
  }
}

Getting Started

Guides

Webhooks

API Reference

Endpoints

Event Envelope

Supported HOP Events

Payin Example

Payout Example

Account Example

​Event Envelope

​Supported HOP Events

​Payin Example

​Payout Example

​Account Example

Event Envelope

Supported HOP Events

Payin Example

Payout Example

Account Example