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

# Webhooks

Real-time notifications for entity state changes delivered to your configured endpoints.

## Before You Start

Read the following guides before proceeding:

| Guide                                | Why                                              |
| ------------------------------------ | ------------------------------------------------ |
| [Onboarding](https://docs.wirexapp.com/docs/partner-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     |

***

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

```json
{
  "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.

```json
{
  "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).

```json
{
  "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.

```json
{
  "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                       |
| `owner`             | string        | Address of the user who owns the card |
| `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.

```json
{
  "card_id": "64120850-73a1-4df5-a074-d463258c9deb",
  "owner": "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 |
| `owner`          | string        | User wallet 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**

```json
{
  "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)**

```json
{
  "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**

```json
{
  "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)**

```json
{
  "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**

```json
{
  "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)**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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.

```json
{
  "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": {
        "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.

```json
{
  "account_address": "0xB748fA84b9d81CcE82cA2a70D51531b38Ea721d7",
  "token_address": "0x6129ffc5aD58B142DB34D61313EB34dB118C0055",
  "to_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                        |
| ----------------- | ----------------- | ---------------------------------- |
| `account_address` | string            | Account Abstraction wallet address |
| `token_address`   | string            | ERC20 token contract address       |
| `to_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 (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.

```json
{
  "id": "f409ac484633456192de3a2a1d689475",
  "external_id": "0x6072FF6fF23Ae51aB705414A7c58C2b0E4b6192a",
  "status": "Active",
  "verification_status": "Approved",
  "personal_details": {
    "email": "alex.grey@wirexapp.com",
    "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/Reliance 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

```json
{
  "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

```json
{
  "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