Webhook Events

Use the event index to choose your subscriptions, then follow the payload link for the resource you handle. Every delivery uses the same event envelope and headers.

Supported HOP Events

Subscribe through Create Webhook Endpoint or Update Webhook Endpoint. These events are emitted today:

Event	When it is sent	Payload
`payin.received`	Funds are credited to an account.	Payin
`payout.created`	A payout or withdrawal is created.	Payout
`payout.completed`	A payout or withdrawal completes.	Payout
`payout.failed`	A payout or withdrawal fails or is cancelled before release.	Payout
`transfer.completed`	A transfer between two balances of one account completes.	Transfer
`account.created`	Hop provisions the customer’s default account, or a platform creates an end-customer account.	Account
`account.updated`	Hop changes an account’s status.	Account
`payout_destination.updated`	Hop changes a wallet or bank destination’s details or status.	Payout destination
`virtual_account.created`	A virtual account is opened, by you or by Hop. It is `pending`, with no bank details yet.	Virtual account
`virtual_account.updated`	A virtual account’s `status` changes, including when it becomes `active` with its bank details.	Virtual account
`virtual_account_group.created`	A virtual account group is opened on an account, by you or by Hop.	Virtual account group
`virtual_account_group.updated`	A group’s `status`, `onboarding_status` or `requirements` change.	Virtual account group

A trading-account payout rejected at creation for INSUFFICIENT_FUNDS or CREDIT_LIMIT_EXCEEDED emits payout.failed without a preceding payout.created. Match data.id to error.details.payout_id from the create response.

Reserved event names

The API accepts these subscriptions, but neither event is emitted today:

Event	Behavior
`payin.returned`	Reserved. Subscribing delivers nothing; do not build a flow that waits for it.
`transfer.failed`	Accepted for compatibility. Transfers are synchronous: a failure comes back in the response to your request, and no event follows.

Unsupported event names

Any other event name is rejected with 422 Unprocessable Entity when you create or update an endpoint. Withdrawals raise payout.* events; withdraw.* is not an event family.

Example: unsupported withdraw.completed subscription

{
  "error": {
    "type": "service_validation",
    "code": "INVALID_FIELD_VALUE",
    "message": "Invalid value for events. Allowed: ['account.created', 'account.updated', 'payin.received', 'payin.returned', 'payout.completed', 'payout.created', 'payout.failed', 'payout_destination.updated', 'transfer.completed', 'transfer.failed', 'virtual_account.created', 'virtual_account.updated', 'virtual_account_group.created', 'virtual_account_group.updated']",
    "details": {
      "field": "events",
      "value": ["withdraw.completed"],
      "allowed_values": [
        "account.created",
        "account.updated",
        "payin.received",
        "payin.returned",
        "payout.completed",
        "payout.created",
        "payout.failed",
        "payout_destination.updated",
        "transfer.completed",
        "transfer.failed",
        "virtual_account.created",
        "virtual_account.updated",
        "virtual_account_group.created",
        "virtual_account_group.updated"
      ]
    }
  },
  "request_id": "0f9c1a7e-2b64-4a1d-9f3e-71c2d84b5a60"
}

Event Envelope

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

{
  "id": "whn_zc8ierkl3h51fun10108m4zd",
  "type": "payout.completed",
  "created": "2026-07-15T02:00:00Z",
  "attempt": 1,
  "account_id": "acct_q47hcaye8ar4rx8qj8xjcxpq",
  "data": {
    "id": "po_vrep9tao1mtmzhw9v4mlc6nd",
    "object": "payout",
    "status": "completed"
  }
}

Envelope fields

Field	Type	Description
`id`	string	Unique delivery-event ID (starts with `whn_`). 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.
`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.

Delivery headers

The request also includes these headers:

Header	Description
`Content-Type`	Always `application/json`.
`User-Agent`	Always `Hop-Webhooks/1.0`. Earlier deliveries sent `HopCore-Webhooks/1.0`; accept both if you filter on this header.
`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.

Payin Payload

Event: payin.received data is the payin object exactly as the Payins API returns it, with every field present. Fields that do not apply are null, not omitted.

Status: pending, completed, failed, or voided.
Credited balance: deposit_destination is {"type": "trading_account"} or {"type": "virtual_account", "virtual_account_id": "va_…"}.

Payin fields

Identifiers: id, object, account_id.
Amount: amount, currency, amount_in_usd.
State: status, payin_type.
Deposit: deposit_destination, payment_rail, note.
Crypto: network, txn_hash, destination_wallet_id, destination_address, source_address.
Sender: sender_name, sender_account_masked, sender_bank_code, sender_country.
Lifecycle: initiated_at, completed_at, failed_at, failed_reason, voided_at, voided_reason.
Audit: created, updated, created_by, updated_by.

Example: payin.received

{
  "id": "whn_zc8ierkl3h51fun10108m4zd",
  "type": "payin.received",
  "created": "2026-07-15T02:00:00Z",
  "attempt": 1,
  "account_id": "acct_q47hcaye8ar4rx8qj8xjcxpq",
  "data": {
    "id": "pi_do8ybzwx3i5122p10o6v0ln0",
    "object": "payin",
    "account_id": "acct_q47hcaye8ar4rx8qj8xjcxpq",
    "amount": "1000.00",
    "currency": "USD",
    "status": "completed",
    "deposit_destination": {"type": "virtual_account", "virtual_account_id": "va_bhrfpcjne3fsfc0y2ufnxtxu"},
    "network": null,
    "amount_in_usd": "1000.00",
    "payment_rail": "swift",
    "note": "Invoice 4471",
    "txn_hash": null,
    "destination_wallet_id": null,
    "destination_address": null,
    "source_address": null,
    "sender_name": "Acme Pte Ltd",
    "sender_account_masked": "****4321",
    "sender_bank_code": "DBSSSGSG",
    "sender_country": "SG",
    "initiated_at": "2026-07-15T01:55:00Z",
    "completed_at": "2026-07-15T02:00:00Z",
    "failed_at": null,
    "failed_reason": null,
    "voided_at": null,
    "voided_reason": null,
    "payin_type": "standard",
    "created": "2026-07-15T01:55:00Z",
    "updated": "2026-07-15T02:00:00Z",
    "created_by": null,
    "updated_by": null
  }
}

Payout Payload

Events: payout.created, payout.completed, payout.failed These events cover both payouts and withdrawals. data.funding_source.type tells them apart.

Resource shape: data is the expanded payout object, matching an item in List Payouts. Get Payout returns a different shape.
Nested resources: beneficiary and payout_destination are included. Each is null when the payout was created without that stored resource.
Account context: account_id appears only in the envelope, never inside data.
Status: pending_approval, pending, processing, completed, failed, cancelled, returned, or voided. A payout.failed delivery has data.status of failed or cancelled.

A payout that the receiving bank later returns has no event of its own, and Hop emits no webhook for it. Detect returns by reading the payout’s status through the Payouts API.

Payout fields

Identifiers: id, object.
Recipient: beneficiary, payout_destination.
Amount and fee: amount, currency, amount_in_usd, platform_fee.
Funding: funding_source.
State: status, payout_type.
Tracking: tracking_details (uetr, imad, omad, trace_number), the compatibility field uetr, network, txn_hash, note.
Lifecycle: initiated_at, submitted_at, completed_at, failed_at, failed_reason, voided_at, voided_reason.
Audit: created, updated, created_by, updated_by.

Example: payout.completed

{
  "id": "whn_07y8wjmjwficyq7u4s49ounu",
  "type": "payout.completed",
  "created": "2026-07-15T03:00:00Z",
  "attempt": 1,
  "account_id": "acct_q47hcaye8ar4rx8qj8xjcxpq",
  "data": {
    "id": "po_vrep9tao1mtmzhw9v4mlc6nd",
    "object": "payout",
    "beneficiary": {
      "id": "bene_6bcsgsmlgs3k0axt3xb60zsr",
      "object": "beneficiary",
      "beneficiary_type": "business",
      "display_name": "Example Supplier",
      "status": "active",
      "verified": true,
      "self_owned": false,
      "created": "2026-06-01T00:00:00Z",
      "updated": "2026-06-01T00:00:00Z"
    },
    "payout_destination": {
      "id": "dest_sspfvxt49881rz39nep2abs4",
      "object": "payout_destination",
      "country": "US",
      "type": "bank_account",
      "currency": "USD",
      "status": "active",
      "account_name": "Example Supplier LLC",
      "bank_name": "Example Bank",
      "routing_number": "021000021",
      "account_number_last4": "****7890",
      "created": "2026-06-01T00:00:00Z",
      "updated": "2026-06-01T00:00:00Z"
    },
    "amount": "250.00",
    "currency": "USD",
    "amount_in_usd": "250.00",
    "status": "completed",
    "funding_source": {"type": "trading_account"},
    "platform_fee": null,
    "uetr": null,
    "tracking_details": {
      "uetr": null,
      "imad": null,
      "omad": null,
      "trace_number": null
    },
    "payout_type": "standard",
    "network": null,
    "txn_hash": null,
    "initiated_at": "2026-07-15T02:45:00Z",
    "submitted_at": "2026-07-15T02:46:00Z",
    "completed_at": "2026-07-15T03:00:00Z",
    "failed_at": null,
    "failed_reason": null,
    "voided_at": null,
    "voided_reason": null,
    "note": "Monthly payment",
    "created": "2026-07-15T02:45:00Z",
    "updated": "2026-07-15T03:00:00Z",
    "created_by": "ak_9a3yfd2ro3jeoqqalbx8jew1",
    "updated_by": null
  }
}

Transfer Payload

Event: transfer.completed data is the transfer object. Its id starts with trf_. Each leg (source and destination) is {"type": "trading_account"} or {"type": "virtual_account", "virtual_account_id": "va_…"}.

Transfer fields

Identifiers: id, object, account_id.
Balances: source, destination.
Amount: amount, currency.
State: status.
References: reference, internal_note.
Audit: created, updated, created_by, updated_by.

Example: transfer.completed

{
  "id": "whn_ujzde8gxd6ncf10epf91dhod",
  "type": "transfer.completed",
  "created": "2026-07-15T05:00:00Z",
  "attempt": 1,
  "account_id": "acct_q47hcaye8ar4rx8qj8xjcxpq",
  "data": {
    "id": "trf_tcpa3m6ebebylpn75s30sgsc",
    "object": "transfer",
    "account_id": "acct_q47hcaye8ar4rx8qj8xjcxpq",
    "source": {"type": "trading_account"},
    "destination": {"type": "virtual_account", "virtual_account_id": "va_bhrfpcjne3fsfc0y2ufnxtxu"},
    "amount": "250.00",
    "currency": "USD",
    "status": "completed",
    "reference": "Fund operating account",
    "internal_note": null,
    "created": "2026-07-15T05:00:00Z",
    "updated": "2026-07-15T05:00:00Z",
    "created_by": "ak_9a3yfd2ro3jeoqqalbx8jew1",
    "updated_by": null
  }
}

Account Payload

Events: account.created, account.updated

Creation: account.created covers the default account Hop provisions when your customer is approved and every end-customer account a platform creates through the API. The latter echoes your own request, so a service that only listens to webhooks still sees every account; match it to your request by data.id.
Updates: account.updated is sent only when Hop changes the account’s status. Your own API updates and changes to other fields do not emit it.
Identity and balances: legal_name, business_registration_number, address, created_by, and updated_by are always null. Read identity through the Accounts API. balances is always an empty array.
Identifier and status: id starts with acct_; status is active, suspended, or deactivated.

Account fields

Identifiers and name: id, object, customer_id, name.
State: status.
Identity: legal_name, business_registration_number, address.
Balances: balances.
Audit: created, updated, created_by, updated_by.

Example: account.updated

{
  "id": "whn_zdoc9is0j8ht9lgmxg9edn58",
  "type": "account.updated",
  "created": "2026-07-15T04:00:00Z",
  "attempt": 1,
  "account_id": "acct_q47hcaye8ar4rx8qj8xjcxpq",
  "data": {
    "id": "acct_q47hcaye8ar4rx8qj8xjcxpq",
    "object": "account",
    "customer_id": "cus_10uu44q9ziih39vh89wbeg11",
    "name": "Main Account",
    "status": "active",
    "legal_name": null,
    "business_registration_number": null,
    "address": null,
    "balances": [],
    "created": "2026-07-14T04:00:00Z",
    "updated": "2026-07-15T04:00:00Z",
    "created_by": null,
    "updated_by": null
  }
}

Payout Destination Payload

Event: payout_destination.updated data is the payout destination exactly as the Payout Destinations API returns it, so account numbers and wallet addresses stay masked. Fields that do not apply are null, not omitted. The event fires on every change Hop makes to a destination, wallet or bank:

Hop approves a wallet: status moves from pending to active, and payouts to it can be created from then on.
Hop rejects a wallet: status moves from pending to disabled, and the wallet cannot be paid.
Hop corrects a destination’s details or status.

Each delivery carries the destination as it stands after the change. Creating a destination does not emit the event, and neither do your own changes through the API (update, disable, delete). A payout to a destination that is not active is rejected with 422 PAYOUT_DESTINATION_INACTIVE.

Example: payout_destination.updated

{
  "id": "whn_q2m8vk4zt61bnq7hdxw3jfa9",
  "type": "payout_destination.updated",
  "created": "2026-01-16T09:30:00Z",
  "attempt": 1,
  "account_id": "acct_ka44qsvpo8q3wtzuwfqf0h6u",
  "data": {
    "id": "dest_2pm8vkz4ts61bnq7hdxw3jfa",
    "object": "payout_destination",
    "beneficiary_id": "bene_9gt1ummgx127biovlurm9mq2",
    "country": "US",
    "payment_rails": ["crypto"],
    "type": "wallet",
    "label": "Treasury wallet",
    "currency": "USDC",
    "network": "ethereum",
    "status": "active",
    "account_name": null,
    "account_number_last4": null,
    "account_type": null,
    "routing_number": null,
    "swift_code": null,
    "iban_masked": null,
    "clabe_last4": null,
    "pix_key_last4": null,
    "wallet_address_masked": "0x742d****0bEb",
    "bank_name": null,
    "bank_address": null,
    "correspondent_bank_name": null,
    "correspondent_bank_address": null,
    "correspondent_bank_swift": null,
    "account_holder": null,
    "created": "2026-01-15T11:00:00Z",
    "updated": "2026-01-16T09:30:00Z",
    "created_by": "ak_0ub5w2xr8yl3qks6tcdn7m4v",
    "updated_by": "hop_admin"
  }
}

Virtual Account Payload

Events: virtual_account.created, virtual_account.updated data is the virtual account exactly as Get Virtual Account returns it, with balances as they stood when the event was sent.

Creation: virtual_account.created is sent for every virtual account opened on your accounts. One you open through the API echoes your own request; one Hop opens for you is announced only here. It is always pending with every bank detail null, so do not publish it as funding instructions.
Updates: virtual_account.updated is sent when the virtual account’s status changes. pending to active means the bank details have been issued and provisioned_at is set: share them with payers from then on. active to frozen and back means Hop blocked or released balance movements, and disabled means Hop closed the virtual account. Balance changes do not emit it (use payin.* and payout.*), and neither do label changes you make.
Order and duplicates: deliveries can repeat or arrive out of order. Each one carries the virtual account as it stood when the event was sent, so keep the one with the latest updated for each data.id, and read the virtual account when in doubt.

Example: virtual_account.updated (activated)

{
  "id": "whn_2r6t9v3x7z1b5n8q4w0e6y3u",
  "type": "virtual_account.updated",
  "created": "2026-01-15T10:12:04Z",
  "attempt": 1,
  "account_id": "acct_ka44qsvpo8q3wtzuwfqf0h6u",
  "data": {
    "id": "va_6b3n9k1q4t7w2z5m8p0r3d6f",
    "object": "virtual_account",
    "account_id": "acct_ka44qsvpo8q3wtzuwfqf0h6u",
    "currency": "EUR",
    "status": "active",
    "label": "EU Collections",
    "balances": {
      "available": "0.00",
      "pending_payin": "0.00",
      "held_for_payout": "0.00",
      "total": "0.00"
    },
    "beneficiary_name": "Acme GmbH",
    "bank_name": "Example Bank",
    "account_number": null,
    "account_number_last4": "****3000",
    "iban": "DE89370400440532013000",
    "swift_bic": "DEUTDEFFXXX",
    "routing_number": null,
    "routing_number_type": null,
    "bank_address": {
      "address_line": "1 Bank Street",
      "city": "Frankfurt",
      "region": null,
      "postal_code": "60311",
      "country": "DE"
    },
    "beneficiary_address": {
      "address_line": "22 Hauptstrasse",
      "city": "Berlin",
      "region": null,
      "postal_code": "10115",
      "country": "DE"
    },
    "provisioned_at": "2026-01-15T10:12:00Z",
    "created": "2026-01-15T10:00:00Z",
    "updated": "2026-01-15T10:12:00Z",
    "created_by": "ak_3f7k9m2p5r8t1v4x6z0b3n5q",
    "updated_by": null
  }
}

Virtual Account Group Payload

Events: virtual_account_group.created, virtual_account_group.updated data is the group exactly as Get Virtual Account Group returns it, including requirements and the agreements summary.

Creation: virtual_account_group.created is sent for every group opened on your accounts. A group you open through the API echoes your own request; a group Hop opens for you is announced only here. Match it by data.id.
Updates: virtual_account_group.updated is sent whenever the group’s status, onboarding_status or requirements change: onboarding needs more information (onboarding_status is action_needed and requirements lists what to provide), moves to review, is approved or rejected, or Hop enables or disables the group. Your own changes, such as updating the account, uploading a document or accepting agreements, emit it once they change the group’s status or requirements.
Order and duplicates: deliveries can repeat or arrive out of order. Each one carries the group as it stood when the event was sent, so keep the one with the latest updated for each data.id, and read the group when in doubt.
First events: opening a group usually sends virtual_account_group.created followed shortly by virtual_account_group.updated as the first requirements arrive.

Example: virtual_account_group.updated

{
  "id": "whn_7k3m9p2r5t8v1x4z6b0n3q5w",
  "type": "virtual_account_group.updated",
  "created": "2026-01-16T08:12:05Z",
  "attempt": 1,
  "account_id": "acct_ka44qsvpo8q3wtzuwfqf0h6u",
  "data": {
    "id": "vag_7m2k9x4c1b6v3n8q5z0j2p7t",
    "object": "virtual_account_group",
    "account_id": "acct_ka44qsvpo8q3wtzuwfqf0h6u",
    "type": "business_virtual_accounts",
    "status": "pending",
    "onboarding_status": "action_needed",
    "enabled_at": null,
    "suspended_at": null,
    "closed_at": null,
    "requirements": [
      {
        "key": "req_9c1f4a7b2e06d38a5f4c1b72",
        "type": "document",
        "label": "Proof of identity",
        "associated_person_id": "aap_5r8t1v4x6z0b3n5q7w2e9y4u",
        "is_target_resolved": true,
        "accepted_document_types": ["passport", "national_id"],
        "reason": null,
        "verification_url": null,
        "verification_url_expires_at": null
      }
    ],
    "agreements": {
      "status": "complete",
      "pending_ids": []
    },
    "created": "2026-01-15T10:00:00Z",
    "updated": "2026-01-16T08:12:00Z",
    "created_by": "ak_3f7k9m2p5r8t1v4x6z0b3n5q",
    "updated_by": null
  }
}

Getting started

API basics

Endpoints

Webhooks

Supported HOP Events

Reserved event names

Unsupported event names

Event Envelope

Envelope fields

Delivery headers

Payin Payload

Payout Payload

Transfer Payload

Account Payload

Payout Destination Payload

Virtual Account Payload

Virtual Account Group Payload

​Supported HOP Events

​Reserved event names

​Unsupported event names

​Event Envelope

​Envelope fields

​Delivery headers

​Payin Payload

​Payout Payload

​Transfer Payload

​Account Payload

​Payout Destination Payload

​Virtual Account Payload

​Virtual Account Group Payload

Supported HOP Events

Reserved event names

Unsupported event names

Event Envelope

Envelope fields

Delivery headers

Payin Payload

Payout Payload

Transfer Payload

Account Payload

Payout Destination Payload

Virtual Account Payload

Virtual Account Group Payload