--- updatedAt: 2026-01-27T02:14:00.000Z agentTools: projectIndex: https://partner.wirexpaychain.com/llms.txt --- # Webhooks V2
## Webhooks The Business API provides a webhook publisher service that delivers real-time notifications to partner systems when entity state changes occur. Webhooks are delivered as HTTP POST requests to configured company webhook URLs. ### Webhook Delivery **Delivery Model:** Fire-and-forget HTTP POST requests with JSON payloads. No authentication headers are added to webhook requests. Partners are responsible for validating webhook origin through network-level controls or payload verification. **Timeout:** 10 seconds per request. Failed deliveries are logged but not retried. **Content-Type:** `application/json` ### 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 requiring user decision | | `/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 | ### Webhook Payloads #### Wallet Webhook (`/v2/webhooks/wallets`) Delivered when wallet state changes (creation, confirmation status). ```json { "wallet_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE", "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 (`/v2/webhooks/balances`) Delivered when token balance changes on a wallet. ```json { "wallet_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE", "token_symbol": "USDT", "token_address": "0x6b175474e89094c44da98b954eedeac495271d0f", "balance": 100.00056, "reference_balance": 100.00056, "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 (`/v2/webhooks/cards`) Delivered when card state changes (issuance, activation, blocking, status updates). ```json { "id": "00000000-0000-0000-0000-000000000001", "card_wallet_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE", "status": "Active", "status_reason": "User", "previous_status": "NotActivated", "generation": "Gen2", "provider": "Wirex", "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-02T00:00:00Z", "card_data": { "name_on_card": "Alex Grey", "payment_system": "Visa", "card_number_last_4": "5678", "expiry_date": "01/2028", "format": "Virtual", "card_name": "MC ****5678" }, "delivery_address": { "line1": "123 Main St", "line2": "Suite 200", "city": "San Francisco", "state": "CA", "country": "US", "zip_code": "94107" } } ``` | 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 (`/v2/webhooks/card-limits`) Delivered when card spending limits or usage changes. ```json { "card_id": "00000000-0000-0000-0000-000000000001", "transaction_limit": 500.00, "daily_limit": 1000.00, "daily_usage": 200.00, "monthly_limit": 5000.00, "monthly_usage": 1500.00, "lifetime_limit": 100000.00, "lifetime_usage": 25000.00 } ``` | Field | Type | Description | | ------------------- | ------------- | ------------------------------------- | | `card_id` | string (UUID) | Card identifier | | `owner` | address | 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 (`/v2/webhooks/3ds`) Delivered when a card transaction requires 3D Secure confirmation. ```json { "card_id": "00000000-0000-0000-0000-000000000001", "owner": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE", "transaction_id": "00000000000000000000000000000001", "merchant_name": "Amazon", "amount": "100.00", "currency": "USD", "card_last_4": "1234" } ``` | Field | Type | Description | | ---------------- | ------------- | ----------------------------- | | `card_id` | string (UUID) | Card used for the transaction | | `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 (`/v2/webhooks/activities`) Delivered when transaction or activity state changes. ```json { "id": "00000000-0000-0000-0000-000000000001", "user_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE", "type": "CardTransaction", "status": "Completed", "status_reason": null, "direction": "Outbound", "source": { "type": "Card", "card": { "id": "00000000-0000-0000-0000-000000000001", "pan_last": "1234", "payment_system": "Visa" } }, "destination": { "type": "Merchant", "merchant": { "id": "00000000-0000-0000-0000-000000000001", "name": "Amazon" } }, "source_amount": { "amount": 100.0, "token_symbol": "USDT", "token_address": "0x..." }, "destination_amount": { "amount": 100.0, "currency": "USD" }, "rate": { "ticker": "USD/USDT", "rate": 1.0 }, "created_at": "2024-01-01T00:00:00Z", "activity_steps": [ { "type": "Initiated", "status": "Completed", "created_at": "2024-01-01T00:00:00Z", "completed_at": "2024-01-01T00:00:01Z" } ] } ``` | Field | Type | Description | | -------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | string (UUID) | Activity identifier | | `user_address` | string | User wallet address | | `type` | enum | `Deposit`, `Withdrawal`, `Exchange`, `Sepa`, `FasterPayment`, `AchPull`, `AchPush`, `Swift`, `Spei`, `CardTransaction`, `ExternalCardTransaction`, `Crypto`, `CardFeesPayment`, `YieldClaim`, `CardTransfer` | | `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) | | `activity_steps` | array | Transaction processing steps | #### Recipient Webhook (`/v2/webhooks/recipients`) Delivered when recipient is created or updated. ```json { "id": "00000000-0000-0000-0000-000000000001", "personal_info": { "first_name": "Alex", "last_name": "Grey", "is_business": false }, "payment_details": [ { "id": "00000000-0000-0000-0000-000000000002", "type": "Sepa", "currencies": ["EUR"], "sepa": { "iban": "DE89370400440532013000", "bic": "COBADEFF" } } ] } ``` | 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) | #### ERC Withdrawal Webhook (`/v2/webhooks/erc-withdrawals`) Delivered when ERC20 withdrawal is requested and pending user signature. ```json { "account_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE", "token_address": "0x71C7656EC7AB88B098DEFB751B7401B5F6D8976F", "to_address": "0xF4D2A0E30C7983EF65DC0DD938BED82C7E3745DB", "amount": 100.0, "valid_after": "2024-01-01T00:00:00Z", "valid_before": "2024-01-02T00:00:00Z", "hash": "0x8A7B6C5D4E3F2A1B0C9D8E7F6A5B4C3D2E1F0A9B8C7D6E5F4A3B2C1D0E9F817", "call_data": "3F7D9E1C5A2B804D6E93F7C1A0B5D8E29F4A3B7C6D5E0F1A2B3C4D5E6F7A8B9" } ``` | 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 |