Webhooks

Before You Start

Read the following guides before proceeding:

Guide	Why
Onboarding	Webhook base URL is configured during onboarding

Overview

The BaaS API delivers real-time notifications to your systems when entity state changes occur. Webhooks are delivered as HTTP POST requests to your configured webhook base URL.

Delivery Model

Method: HTTP POST with JSON payload
Timeout: 10 seconds per request
Retries: Failed deliveries are logged but not automatically retried
Authentication: No authentication headers are added to webhook requests

You are responsible for validating webhook origin through network-level controls (IP allowlisting) or payload verification.

Content-Type

All webhooks are delivered with Content-Type: application/json.

V2 Webhook Endpoints

Path	Entity	Description
`/v2/webhooks/wallets`	Wallet	Wallet creation and status changes
`/v2/webhooks/balances`	Balance	Token balance updates
`/v2/webhooks/cards`	Card	Card status and data changes
`/v2/webhooks/card-limits`	Card Limit	Spending limit and usage updates
`/v2/webhooks/3ds`	3DS Confirmation	3D Secure transaction confirmations
`/v2/webhooks/activities`	Activity	Transaction and activity feed updates
`/v2/webhooks/recipients`	Recipient	Recipient creation and updates
`/v2/webhooks/erc-withdrawals`	ERC Withdrawal	Pending ERC20 withdrawal requests
`/v2/webhooks/user`	User	User profile, verification, and capability changes
`/v2/webhooks/debt-cases`	Debt Case	Operations that left a user account in debt
`/v2/webhooks/corporations`	Corporation	Corporate profile and verification changes

V1 Webhook Endpoints (Legacy)

Note: These endpoints use a legacy format that will be replaced in a future release.

Path	Entity	Description
`/webhook/users`	User	User status and verification status changes
`/webhook/accounts/fiat`	Bank Account	Bank account creation and details updates

Webhook Payloads

Wallet Webhook

Endpoint: POST {base_url}/v2/webhooks/wallets

Delivered when wallet state changes (creation, confirmation status).

{
  "wallet_address": "0xe9ba524306ECd3D836Cf65d67F52E5C1AA0a1997",
  "wallet_name": "Main Wallet",
  "wallet_status": "Confirmed",
  "wallet_type": "Primary"
}

Field	Type	Description
`wallet_address`	string	Ethereum address of the wallet
`wallet_name`	string	Display name of the wallet
`wallet_status`	enum	`Unknown`, `Confirmed`, `Rejected`
`wallet_type`	enum	`Primary`, `Secondary`, `Global`, `Card`

Balance Webhook

Endpoint: POST {base_url}/v2/webhooks/balances

Delivered when token balance changes on a wallet.

{
  "wallet_address": "0xAAFF0821A09A1Aac28B72dD3Ff410A7ea5FEb874",
  "token_symbol": "WUSD",
  "token_address": "0x0774164DC20524Bb239b39D1DC42573C3E4C6976",
  "balance": 2,
  "reference_balance": 1.68,
  "reference_currency": "EUR"
}

Field	Type	Description
`wallet_address`	string	Wallet address this balance belongs to
`token_symbol`	string	Token symbol (e.g., USDT, USDC)
`token_address`	string	Contract address of the token
`balance`	float	Available token balance
`reference_balance`	float	Balance converted to reference currency
`reference_currency`	string	ISO 4217 currency code (default: EUR)

Card Webhook

Endpoint: POST {base_url}/v2/webhooks/cards

Delivered when card state changes (issuance, activation, blocking, status updates).

{
  "id": "64120850-73a1-4df5-a074-d463258c9deb",
  "card_wallet_address": "0xAAFF0821A09A1Aac28B72dD3Ff410A7ea5FEb874",
  "status": "Closed",
  "status_reason": "User",
  "generation": "Gen2",
  "provider": "Wirex",
  "card_data": {
    "name_on_card": "ALEX GREY",
    "payment_system": "Visa",
    "card_number_last_4": "0333",
    "expiry_date": "02/27",
    "format": "Plastic",
    "card_name": "Main Card"
  }
}

Field	Type	Description
`id`	string (UUID)	Unique card identifier
`card_wallet_address`	string	Linked wallet address
`status`	enum	`Requested`, `NotActivated`, `Active`, `Closed`, `Blocked`
`status_reason`	string	Reason for current status
`previous_status`	enum	Status before current state
`generation`	enum	`Gen1`, `Gen2`
`provider`	enum	`Wirex`, `Bridge`
`card_data`	object	Card display information
`delivery_address`	object	Physical card delivery address (optional)

Card Limit Webhook

Endpoint: POST {base_url}/v2/webhooks/card-limits

Delivered when card spending limits or usage changes.

{
  "card_id": "64120850-73a1-4df5-a074-d463258c9deb",
  "transaction_limit": -1,
  "daily_limit": 0.01,
  "daily_usage": 45.99,
  "monthly_limit": -1,
  "monthly_usage": 45.99,
  "lifetime_limit": -1,
  "lifetime_usage": 45.99
}

Field	Type	Description
`card_id`	string (UUID)	Card identifier
`transaction_limit`	float	Maximum single transaction amount
`daily_limit`	float	Daily spending limit
`daily_usage`	float	Amount spent today
`monthly_limit`	float	Monthly spending limit
`monthly_usage`	float	Amount spent this month
`lifetime_limit`	float	Lifetime spending limit
`lifetime_usage`	float	Total amount spent

3DS Confirmation Webhook

Endpoint: POST {base_url}/v2/webhooks/3ds

Delivered when a card transaction requires 3D Secure confirmation.

{
  "card_id": "64120850-73a1-4df5-a074-d463258c9deb",
  "user_address": "0xAAFF0821A09A1Aac28B72dD3Ff410A7ea5FEb874",
  "transaction_id": "1b0b99c8-566c-45e5-8c82-4151edd078f5",
  "merchant_name": "Amazon UK",
  "amount": "127.15",
  "currency": "USD",
  "card_last_4": "0333"
}

Field	Type	Description
`card_id`	string (UUID)	Card used for the transaction
`user_address`	string	EOA address of the user who owns the card
`owner`	string	Deprecated. Mirrors `user_address`
`transaction_id`	string	Issuer transaction identifier
`merchant_name`	string	Merchant name
`amount`	string	Transaction amount
`currency`	string	ISO 4217 currency code
`card_last_4`	string	Last 4 digits of card number

Activity Webhook

Endpoint: POST {base_url}/v2/webhooks/activities

Delivered when transaction or activity state changes.

Example: Crypto Deposit

{
  "id": "eac95aab-ca2d-f6e4-ebd4-92312133a139",
  "user_address": "0x39Bdb53DDD0dd3666109f6839d62eE2a516f4b11",
  "type": "Crypto",
  "status": "Completed",
  "direction": "Inbound",
  "source": {
    "type": "ExternalWallet",
    "wallet": {
      "address": "0x3aa11B9433d49cc97EF8b9d723BdCDe31B04393A"
    }
  },
  "destination": {
    "type": "Wallet",
    "wallet": {
      "address": "0x7033b4FC3553E6F2ca0bd1E62f85AC5780A4Eb63"
    }
  },
  "source_amount": {
    "amount": 25.91,
    "token_symbol": "EURC",
    "token_address": "0x6129ffc5aD58B142DB34D61313EB34dB118C0055"
  },
  "destination_amount": {
    "amount": 25.91,
    "token_symbol": "WEUR",
    "token_address": "0x5c55F314624718019A326F16a62A05D6C6d8C8A2"
  },
  "operations": [
    {
      "hash": "0xa1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
      "operation_amount": {
        "amount": 25.91,
        "token_symbol": "WEUR",
        "token_address": "0x5c55F314624718019A326F16a62A05D6C6d8C8A2"
      },
      "rate": {
        "ticker": "EURC/WEUR",
        "rate": 1
      }
    }
  ],
  "created_at": "2024-01-01T10:15:30.000Z",
  "activity_steps": [
    {
      "type": "Initiated",
      "status": "Completed",
      "created_at": "2024-01-01T10:15:30.000Z",
      "completed_at": "2024-01-01T10:15:30.000Z"
    },
    {
      "type": "CryptoIn",
      "status": "Completed",
      "created_at": "2024-01-01T10:15:30.000Z",
      "completed_at": "2024-01-01T10:15:45.000Z"
    }
  ]
}

Example: Crypto Transfer (Outbound)

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "user_address": "0x39Bdb53DDD0dd3666109f6839d62eE2a516f4b11",
  "type": "Crypto",
  "status": "Completed",
  "direction": "Outbound",
  "source": {
    "type": "Wallet",
    "wallet": {
      "address": "0x7033b4FC3553E6F2ca0bd1E62f85AC5780A4Eb63"
    }
  },
  "destination": {
    "type": "ExternalWallet",
    "wallet": {
      "address": "0x3aa11B9433d49cc97EF8b9d723BdCDe31B04393A"
    }
  },
  "source_amount": {
    "amount": 100.00,
    "token_symbol": "WUSD",
    "token_address": "0x0774164DC20524Bb239b39D1DC42573C3E4C6976"
  },
  "destination_amount": {
    "amount": 100.00,
    "token_symbol": "USDC",
    "token_address": "0x7Af7cDbd557eD302F7538Db1e3d094C8BBcA665c"
  },
  "operations": [
    {
      "hash": "0xdef123456789abcdef123456789abcdef123456789abcdef123456789abcdef12",
      "operation_amount": {
        "amount": -100.00,
        "token_symbol": "WUSD",
        "token_address": "0x0774164DC20524Bb239b39D1DC42573C3E4C6976"
      },
      "rate": {
        "ticker": "USDC/WUSD",
        "rate": 1
      }
    }
  ],
  "created_at": "2024-01-01T11:30:00.000Z",
  "activity_steps": [
    {
      "type": "Initiated",
      "status": "Completed",
      "created_at": "2024-01-01T11:30:00.000Z",
      "completed_at": "2024-01-01T11:30:00.000Z"
    },
    {
      "type": "CryptoOut",
      "status": "Completed",
      "created_at": "2024-01-01T11:30:00.000Z",
      "completed_at": "2024-01-01T11:30:15.000Z"
    }
  ]
}

Example: SEPA Deposit

{
  "id": "ea6fbc2c-b8da-4a7b-99d1-6a2220352d02",
  "user_address": "0x1d595bFAc81F231Ebc30950B8B08F2beEb97934B",
  "type": "Sepa",
  "status": "Completed",
  "direction": "Inbound",
  "source": {
    "type": "SepaBankAccount",
    "bank_account": {
      "iban": "GB82WEST12345698765432",
      "bic": "WESTGB2L",
      "owner_name": "Alex Grey",
      "is_business": false
    }
  },
  "destination": {
    "type": "Wallet",
    "wallet": {
      "address": "0x6fb0fCA78F4b717fbAaB89c96754200355554832"
    }
  },
  "source_amount": {
    "amount": 55.93,
    "currency": "EUR"
  },
  "destination_amount": {
    "amount": 55.93,
    "token_symbol": "WEUR",
    "token_address": "0x5c55F314624718019A326F16a62A05D6C6d8C8A2"
  },
  "reference": "Payment reference",
  "operations": [
    {
      "hash": "0x456789abcdef123456789abcdef123456789abcdef123456789abcdef12345678",
      "operation_amount": {
        "amount": 55.93,
        "token_symbol": "WEUR",
        "token_address": "0x5c55F314624718019A326F16a62A05D6C6d8C8A2"
      },
      "transaction_amount": {
        "amount": 55.93,
        "currency": "EUR"
      },
      "rate": {
        "ticker": "EUR/WEUR",
        "rate": 1
      }
    }
  ],
  "created_at": "2024-01-01T09:00:00.000Z",
  "activity_steps": [
    {
      "type": "Initiated",
      "status": "Completed",
      "created_at": "2024-01-01T09:00:00.000Z",
      "completed_at": "2024-01-01T09:00:00.000Z"
    },
    {
      "type": "BankIn",
      "status": "Completed",
      "created_at": "2024-01-01T09:00:00.000Z",
      "completed_at": "2024-01-01T09:00:30.000Z"
    },
    {
      "type": "CryptoIn",
      "status": "Completed",
      "created_at": "2024-01-01T09:00:30.000Z",
      "completed_at": "2024-01-01T09:00:45.000Z"
    }
  ]
}

Example: SEPA Transfer (Outbound)

{
  "id": "c3d4e5f6-a7b8-9012-cdef-234567890123",
  "user_address": "0x1d595bFAc81F231Ebc30950B8B08F2beEb97934B",
  "type": "Sepa",
  "status": "Completed",
  "direction": "Outbound",
  "source": {
    "type": "Wallet",
    "wallet": {
      "address": "0x6fb0fCA78F4b717fbAaB89c96754200355554832"
    }
  },
  "destination": {
    "type": "SepaBankAccount",
    "bank_account": {
      "iban": "DE89370400440532013000",
      "bic": "COBADEFFXXX",
      "owner_name": "Alex Grey",
      "is_business": false
    }
  },
  "source_amount": {
    "amount": 200.00,
    "token_symbol": "WEUR",
    "token_address": "0x5c55F314624718019A326F16a62A05D6C6d8C8A2"
  },
  "destination_amount": {
    "amount": 200.00,
    "currency": "EUR"
  },
  "reference": "Invoice payment",
  "operations": [
    {
      "hash": "0x789abcdef123456789abcdef123456789abcdef123456789abcdef1234567890",
      "operation_amount": {
        "amount": -200.00,
        "token_symbol": "WEUR",
        "token_address": "0x5c55F314624718019A326F16a62A05D6C6d8C8A2"
      },
      "transaction_amount": {
        "amount": -200.00,
        "currency": "EUR"
      },
      "rate": {
        "ticker": "EUR/WEUR",
        "rate": 1
      }
    }
  ],
  "created_at": "2024-01-01T14:00:00.000Z",
  "activity_steps": [
    {
      "type": "Initiated",
      "status": "Completed",
      "created_at": "2024-01-01T14:00:00.000Z",
      "completed_at": "2024-01-01T14:00:00.000Z"
    },
    {
      "type": "CryptoOut",
      "status": "Completed",
      "created_at": "2024-01-01T14:00:00.000Z",
      "completed_at": "2024-01-01T14:00:10.000Z"
    },
    {
      "type": "Review",
      "status": "Completed",
      "created_at": "2024-01-01T14:00:10.000Z",
      "completed_at": "2024-01-01T14:00:15.000Z"
    },
    {
      "type": "BankOut",
      "status": "Completed",
      "created_at": "2024-01-01T14:00:15.000Z",
      "completed_at": "2024-01-01T14:01:00.000Z"
    }
  ]
}

Example: ACH Deposit

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "user_address": "0x7e1Cc1685D68D486b22D3880030C24434E3b90a9",
  "type": "AchPush",
  "status": "Completed",
  "direction": "Inbound",
  "source": {
    "type": "AchBankAccount",
    "bank_account": {
      "account_number": "",
      "routing_number": "026073150",
      "owner_name": "Alex Grey",
      "is_business": false
    }
  },
  "destination": {
    "type": "Wallet",
    "wallet": {
      "address": "0xAAFF0821A09A1Aac28B72dD3Ff410A7ea5FEb874"
    }
  },
  "source_amount": {
    "amount": 500.00,
    "currency": "USD"
  },
  "destination_amount": {
    "amount": 500.00,
    "token_symbol": "WUSD",
    "token_address": "0x0774164DC20524Bb239b39D1DC42573C3E4C6976"
  },
  "operations": [
    {
      "hash": "0x123456789abcdef123456789abcdef123456789abcdef123456789abcdef1234",
      "operation_amount": {
        "amount": 500.00,
        "token_symbol": "WUSD",
        "token_address": "0x0774164DC20524Bb239b39D1DC42573C3E4C6976"
      },
      "transaction_amount": {
        "amount": 500.00,
        "currency": "USD"
      },
      "rate": {
        "ticker": "USD/WUSD",
        "rate": 1
      }
    }
  ],
  "created_at": "2024-01-01T08:00:00.000Z",
  "activity_steps": [
    {
      "type": "Initiated",
      "status": "Completed",
      "created_at": "2024-01-01T08:00:00.000Z",
      "completed_at": "2024-01-01T08:00:00.000Z"
    },
    {
      "type": "BankIn",
      "status": "Completed",
      "created_at": "2024-01-01T08:00:00.000Z",
      "completed_at": "2024-01-01T08:05:00.000Z"
    },
    {
      "type": "CryptoIn",
      "status": "Completed",
      "created_at": "2024-01-01T08:05:00.000Z",
      "completed_at": "2024-01-01T08:05:15.000Z"
    }
  ]
}

Example: ACH Transfer (Outbound)

{
  "id": "8b4f6e59-4287-4079-a3a3-3742557d07fd",
  "user_address": "0x7e1Cc1685D68D486b22D3880030C24434E3b90a9",
  "type": "AchPush",
  "status": "Completed",
  "direction": "Outbound",
  "source": {
    "type": "Wallet",
    "wallet": {
      "address": "0xAAFF0821A09A1Aac28B72dD3Ff410A7ea5FEb874"
    }
  },
  "destination": {
    "type": "AchBankAccount",
    "bank_account": {
      "account_number": "8310931284",
      "routing_number": "026073150",
      "owner_name": "Alex Grey",
      "is_business": false
    }
  },
  "source_amount": {
    "amount": 34.64,
    "token_symbol": "WUSD",
    "token_address": "0x0774164DC20524Bb239b39D1DC42573C3E4C6976"
  },
  "destination_amount": {
    "amount": 34.64,
    "currency": "USD"
  },
  "operations": [
    {
      "hash": "0xdfe7dfe5633580cf9b34aa2f0021d9a3e53e8d97b99003cf20e3dce9ebba8dea",
      "operation_amount": {
        "amount": -34.64,
        "token_symbol": "WUSD",
        "token_address": "0x0774164DC20524Bb239b39D1DC42573C3E4C6976"
      },
      "rate": {
        "ticker": "USD/WUSD",
        "rate": 1
      }
    }
  ],
  "created_at": "2024-01-01T08:37:35.000Z",
  "activity_steps": [
    {
      "type": "Initiated",
      "status": "Completed",
      "created_at": "2024-01-01T08:37:35.000Z",
      "completed_at": "2024-01-01T08:37:35.000Z"
    },
    {
      "type": "CryptoOut",
      "status": "Completed",
      "created_at": "2024-01-01T08:37:35.000Z",
      "completed_at": "2024-01-01T08:37:35.000Z"
    },
    {
      "type": "BankOut",
      "status": "Completed",
      "created_at": "2024-01-01T08:37:35.000Z",
      "completed_at": "2024-01-01T08:37:47.000Z"
    }
  ]
}

Example: Card Transaction

{
  "id": "927476c4-7c72-458a-abff-9ab5db0d9f1a",
  "user_address": "0x7e1Cc1685D68D486b22D3880030C24434E3b90a9",
  "type": "CardTransaction",
  "sub_type": "POS",
  "status": "Completed",
  "direction": "Outbound",
  "source": {
    "type": "Cards",
    "card": {
      "id": "64120850-73a1-4df5-a074-d463258c9deb",
      "pan_last": "0333",
      "payment_system": "VISA"
    }
  },
  "destination": {
    "type": "Merchant",
    "merchant": {
      "id": "d41d8cd9-8f00-b204-e980-0998ecf8427e",
      "name": "Amazon UK",
      "logo_url": "https://storage.googleapis.com/production-mrs-category-logos/default/shopping_2x.png",
      "full_address": "1 Principal Place, London"
    }
  },
  "source_amount": {
    "amount": 64.24,
    "token_symbol": "WUSD",
    "token_address": "0x0774164DC20524Bb239b39D1DC42573C3E4C6976"
  },
  "destination_amount": {
    "amount": 46.99,
    "currency": "GBP"
  },
  "rate": {
    "ticker": "GBP/WUSD",
    "rate": 1.3670993828474143
  },
  "created_at": "2024-01-01T12:30:00.000Z",
  "activity_steps": [
    {
      "type": "Initiated",
      "status": "Completed",
      "created_at": "2024-01-01T12:30:00.000Z",
      "completed_at": "2024-01-01T12:30:00.000Z"
    },
    {
      "type": "CardOut",
      "status": "Completed",
      "created_at": "2024-01-01T12:30:00.000Z",
      "completed_at": "2024-01-01T12:30:05.000Z"
    }
  ]
}

Example: Card Transfer

{
  "id": "d4e5f6a7-b8c9-0123-def4-567890123456",
  "user_address": "0x7e1Cc1685D68D486b22D3880030C24434E3b90a9",
  "type": "CardTransfer",
  "status": "Completed",
  "direction": "Outbound",
  "source": {
    "type": "Wallet",
    "wallet": {
      "address": "0xAAFF0821A09A1Aac28B72dD3Ff410A7ea5FEb874"
    }
  },
  "destination": {
    "type": "Cards",
    "card": {
      "id": "64120850-73a1-4df5-a074-d463258c9deb",
      "pan_last": "0333",
      "payment_system": "VISA"
    }
  },
  "source_amount": {
    "amount": 50.00,
    "token_symbol": "WUSD",
    "token_address": "0x0774164DC20524Bb239b39D1DC42573C3E4C6976"
  },
  "destination_amount": {
    "amount": 50.00,
    "token_symbol": "USDC",
    "token_address": "0x7Af7cDbd557eD302F7538Db1e3d094C8BBcA665c"
  },
  "operations": [
    {
      "hash": "0xabc123def456789012345678901234567890abcdef1234567890abcdef123456",
      "operation_amount": {
        "amount": -50.00,
        "token_symbol": "WUSD",
        "token_address": "0x0774164DC20524Bb239b39D1DC42573C3E4C6976"
      },
      "rate": {
        "ticker": "USDC/WUSD",
        "rate": 1
      }
    }
  ],
  "created_at": "2024-01-01T13:00:00.000Z",
  "activity_steps": [
    {
      "type": "Initiated",
      "status": "Completed",
      "created_at": "2024-01-01T13:00:00.000Z",
      "completed_at": "2024-01-01T13:00:00.000Z"
    },
    {
      "type": "CryptoOut",
      "status": "Completed",
      "created_at": "2024-01-01T13:00:00.000Z",
      "completed_at": "2024-01-01T13:00:10.000Z"
    }
  ]
}

Field	Type	Description
`id`	string (UUID)	Activity identifier
`user_address`	string	User wallet address
`type`	enum	`Crypto`, `Sepa`, `AchPull`, `AchPush`, `FasterPayment`, `Swift`, `Spei`, `CardTransaction`, `CardTransfer`, `CardFeesPayment`, `YieldClaim`, `Exchange`
`status`	enum	`Pending`, `Completed`, `Failed`
`direction`	enum	`Inbound`, `Outbound`, `Internal`
`source`	object	Source subject (wallet, card, bank account)
`destination`	object	Destination subject (wallet, merchant, bank account)
`source_amount`	object	Amount debited from source
`destination_amount`	object	Amount credited to destination
`rate`	object	Exchange rate applied (optional)
`operations`	array	On-chain operations with transaction hashes
`activity_steps`	array	Transaction processing steps (Initiated, CryptoIn, CryptoOut, BankIn, BankOut, Review, CardOut)
`created_at`	string (ISO 8601)	Activity creation timestamp

Recipient Webhook

Endpoint: POST {base_url}/v2/webhooks/recipients

Delivered when recipient is created or updated.

{
  "id": "77fc49bd-1d7d-41d9-beea-a0aee0dc8c35",
  "personal_info": {
    "first_name": "Alex",
    "last_name": "Grey",
    "is_business": false
  },
  "payment_details": [
    {
      "id": "c56428d0-e1ce-4c4e-a9ca-63bb0f668d00",
      "type": "Sepa",
      "currencies": ["EUR"],
      "sepa": {
        "iban": "MT08CFTE28004000000000006388232",
        "bic": "CFTEMTM1XXX"
      }
    },
    {
      "id": "5d69a2f6-fd1d-4b23-bf41-94057a4ba768",
      "type": "Crypto",
      "currencies": ["USDT"],
      "crypto": {
        "recipient_address": "0xb7830E9DEab7dd10aC5E8F05aadec1b5b29Abc0B",
        "network": "Base"
      }
    },
    {
      "id": "c34908da-d980-4a9c-9b39-4dabd6f6144e",
      "type": "Ach",
      "currencies": ["USD"],
      "ach": {
        "routing_number": "104183619",
        "account_number": "382681756966",
        "bank_name": "Bank of America",
        "legal_address": {
          "country": "US",
          "city": "San Antonio",
          "zip_code": "34923",
          "line1": "123 Main Street",
          "state": "TX"
        }
      }
    }
  ]
}

Field	Type	Description
`id`	string (UUID)	Recipient identifier
`personal_info`	object	Recipient name and type (person/business)
`payment_details`	array	Payment methods (`Crypto`, `Sepa`, `FasterPayment`, `Ach`, `Swift`, `Spei`, `Card`, `Pix`, `Imps`, `Instapay`, `BiFast`, `Nip`, `FpsHk`)

ERC Withdrawal Webhook

Endpoint: POST {base_url}/v2/webhooks/erc-withdrawals

Delivered when ERC20 withdrawal is requested and pending user signature.

{
  "wallet_address": "0xB748fA84b9d81CcE82cA2a70D51531b38Ea721d7",
  "token_address": "0x6129ffc5aD58B142DB34D61313EB34dB118C0055",
  "destination_address": "0x29BBC8aD5AA61C003FBcDC579B85A1623050d1C2",
  "amount": 31.82,
  "valid_after": "2024-01-01T08:44:43.000Z",
  "valid_before": "2024-01-01T09:44:33.000Z",
  "hash": "0x784505480d79cbd1f52e726dae99d80d5356a9addc84168962d4fa6589ba370b",
  "call_data": "e9ae5c530000000000000000000000000000000000000000000000000000000000000000..."
}

Field	Type	Description
`wallet_address`	string	Account Abstraction wallet address
`token_address`	string	ERC20 token contract address
`destination_address`	string	Destination address for withdrawal
`amount`	float	Withdrawal amount
`valid_after`	string (ISO 8601)	Request validity start time
`valid_before`	string (ISO 8601)	Request expiry time
`hash`	string	Calldata and nonce hash
`call_data`	string	Encoded contract call data

User Webhook

Endpoint: POST {base_url}/v2/webhooks/user

Delivered when user profile, verification status, or capability status changes.

The payload structure matches the Get User response for GET /api/v2/user — the same
object, including the profile, residence_address, verification, external_providers and
capabilities sub-objects. Root fields:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "owner": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE",
  "user_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE",
  "chain_id": 8453,
  "profile": { "first_name": "Alex", "last_name": "Grey", "status": "Active" },
  "residence_address": { "line1": "10 Downing Street", "city": "London", "post_code": "SW1A 2AA", "country": "GB" },
  "verification": { "status": "Approved", "levels": [], "documents": [] },
  "external_providers": [],
  "capabilities": []
}

Field	Type	Description
`user_id`	string (UUID)	User account identifier
`user_address`	string	EOA address that owns the account
`chain_id`	integer	Chain the account was registered on
`id`	string (UUID)	Deprecated. Mirrors `user_id`
`owner`	string	Deprecated. Mirrors `user_address`
`profile`	object	Personal details and profile status
`residence_address`	object	Residence address
`verification`	object	Verification status, levels, and documents
`external_providers`	array	Linked external service providers
`capabilities`	array	Capabilities and their statuses

id and owner are retained for backward compatibility only. Read user_id and user_address.

This is the v2 replacement for the legacy /webhook/users endpoint below. Both are delivered — treat the
legacy one as superseded for new integrations.

Debt Case Webhook

Endpoint: POST {base_url}/v2/webhooks/debt-cases

Delivered when operations leave a user account in debt — a card transaction or withdrawal that settled
against the platform but could not be recovered from the user's balance.

{
  "wallet_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE",
  "operations": [
    {
      "transaction_id": "927476c4-7c72-458a-abff-9ab5db0d9f1a",
      "operation_id": "1b0b99c8-566c-45e5-8c82-4151edd078f5",
      "operation_subject_address": "0xAAFF0821A09A1Aac28B72dD3Ff410A7ea5FEb874",
      "operation_amount": "64240000",
      "operation_token_address": "0x0774164DC20524Bb239b39D1DC42573C3E4C6976",
      "operation_hash": "0x28da8dec81198cd43329c92ac5b7bcb048a48495bdbc69fc1c921da72fe42939",
      "operation_type": "CardTransaction",
      "status": "Failed",
      "type": "Debit",
      "status_reason": "InsufficientFunds"
    }
  ]
}

Field	Type	Description
`wallet_address`	string	Wallet address of the user the debt case belongs to
`operations`	array	Operations that form the debt case
`operations[].transaction_id`	string (UUID)	Transaction the operation belongs to
`operations[].operation_id`	string (UUID)	Operation identifier
`operations[].operation_subject_address`	string	Address the operation was executed against
`operations[].operation_amount`	string	Raw amount in the token's smallest unit
`operations[].operation_token_address`	string	Token contract address
`operations[].operation_hash`	string	Hash of the underlying on-chain operation
`operations[].operation_type`	string	Operation type, e.g. `CardTransaction`
`operations[].status`	string	Operation status, e.g. `Failed`
`operations[].type`	string	`Debit` or `Credit`
`operations[].status_reason`	string	Reason for the status. Omitted when not set

operation_amount is a raw integer string in the token's smallest unit, not a decimal amount. Other
webhooks deliver amount as a float — do not parse these the same way.

Corporation Webhook

Endpoint: POST {base_url}/v2/webhooks/corporations

Delivered when a corporate profile or its verification status changes. Only relevant if your integration
onboards corporate accounts.

{
  "corporation_address": "0xb4bB2032A73A53C0Aa7Dc9ee2d9658a978fA7bC2",
  "owner_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE",
  "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
  "corporation_name": "Acme Inc",
  "corporation_type": "LimitedLiability",
  "verification_status": "Approved",
  "status": "Active",
  "registration_number": "12345678",
  "corporation_registration_address": {
    "line1": "10 Downing Street",
    "line2": "Suite 200",
    "city": "London",
    "state": "",
    "country": "GB",
    "postal_code": "SW1A 2AA"
  },
  "corporation_contact_details": {
    "name": "Alex Grey",
    "email": "[email protected]",
    "phone_number": "+447700900123"
  }
}

Field	Type	Description
`corporation_address`	string	On-chain address of the corporate account
`owner_address`	string	EOA address of the account owner
`corporation_id`	string (UUID)	Corporation identifier
`corporation_name`	string	Registered company name
`corporation_type`	enum	`LimitedLiability`, `SoleTrader`, `Partnership`, `PublicLimitedCompany`, `JointStockCompany`, `Charity`
`verification_status`	enum	`Pending`, `Applied`, `InReview`, `Approved`, `Rejected`, `Canceled`
`status`	enum	`Pending`, `Active`, `Blocked`, `Deleted`
`registration_number`	string	Company registration number
`corporation_registration_address`	object	Registered address
`corporation_contact_details`	object	Primary contact name, email, and phone number
`freshdesk_id`	string	Freshdesk identifier. Omitted when not set

The registration address uses postal_code, while a user's residence_address uses post_code. The
two objects are not interchangeable.

User Webhook (Legacy)

Endpoint: POST {base_url}/webhook/users

Note: This is a legacy webhook format that will be replaced with a v2 model in a future release.

Delivered when user status or verification status changes.

{
  "id": "f409ac484633456192de3a2a1d689475",
  "external_id": "0x6072FF6fF23Ae51aB705414A7c58C2b0E4b6192a",
  "status": "Active",
  "verification_status": "Approved",
  "personal_details": {
    "email": "[email protected]",
    "phone_number": "+447700900123",
    "first_name": "Alex",
    "last_name": "Grey",
    "date_of_birth": "1990-01-15",
    "residence_address": {
      "line1": "10 Downing Street",
      "city": "London",
      "country": "GB",
      "postal_code": "SW1A 2AA"
    }
  }
}

Field	Type	Description
`id`	string (UUID)	User ID (same as registration response)
`external_id`	string	User's EOA address
`status`	enum	`Pending`, `Active`, `Blocked`, `Deleted`
`verification_status`	enum	See verification status values below

Verification Status Values:

Status	Description
`None`	No verification submitted
`Applied`	User has unfinished steps in SumSub SDK, or incomplete data was provided during Shared / KYC Sharing via API flows
`Pending`	Verification checks are being executed on Wirex side
`InReview`	Verification checks are being executed on Wirex side
`Approved`	Verification approved - user is ready to use all features
`Canceled`	Verification was rejected - contact Wirex support to resolve
`Rejected`	Verification was rejected - contact Wirex support to resolve

Bank Account Webhook (Legacy)

Endpoint: POST {base_url}/webhook/accounts/fiat

Note: This is a legacy webhook format that will be replaced with a v2 model in a future release.

Delivered when bank account is created or details are updated.

Account Created

{
  "change_type": "Created",
  "id": "1334726cbd7641c09b4124e3e52f53fe",
  "account_type": "Fiat",
  "currency": "EUR",
  "status": "Active",
  "balance": {
    "amount": 0,
    "available_amount": 0
  },
  "details": [],
  "owner_type": "Personal",
  "created_at": "2024-01-15T10:00:00Z"
}

Details Changed

{
  "change_type": "DetailsChanged",
  "id": "1334726cbd7641c09b4124e3e52f53fe",
  "account_type": "Fiat",
  "currency": "EUR",
  "status": "Active",
  "balance": {
    "amount": 0,
    "available_amount": 0
  },
  "details": [
    {
      "id": "8d5a65eb59d94afea64374d45591fe9f",
      "type": "Sepa",
      "status": "Pending",
      "transport_currency": "EUR"
    }
  ],
  "owner_type": "Personal"
}

Field	Type	Description
`change_type`	enum	`Created`, `DetailsChanged`, `StatusChanged`
`id`	string (UUID)	Account identifier
`account_type`	string	Always `Fiat`
`currency`	string	Account currency (`EUR`, `USD`, `GBP`)
`status`	enum	`Active`, `Pending`, `Blocked`, `Closed`
`balance`	object	Current balance information
`details`	array	Bank account details (SEPA, ACH, etc.)
`details[].id`	string (UUID)	Details identifier
`details[].type`	enum	`Sepa`, `Ach`, `FasterPayment`
`details[].status`	enum	`Pending`, `Active`, `Blocked`, `Closed`
`owner_type`	enum	`Personal`, `Business`

Implementation Notes

Implement idempotent handlers to safely process duplicate events
Return a 2xx response within 10 seconds to acknowledge receipt
Log webhook payloads for debugging and audit purposes
Consider queuing webhooks for async processing if your handler requires significant processing time