Webhooks
Webhooks
Webhooks deliver real-time updates for events to your system, eliminating the need to poll the API. When an event occurs, relevant data is pushed to your configured server endpoint.
Setting Up Your Webhook
Step 1: Prepare an HTTPS endpoint
Create an HTTPS URL on your server that accepts POST and PATCH requests with a JSON body and answers with a 2xx status within 10 seconds. Do the real work after answering (for example in a queue), so slow processing never causes a timeout.
Step 2: Register the endpoint
Call Verify Webhook (POST /vaults/verify-webhook) with your url, a secret you choose, and an authMethod. RoxCustody immediately sends a test POST with an empty JSON body ({}) to your URL; your endpoint must answer with a 2xx status, otherwise registration fails with "Webhook url or secret is invalid". A vault has one webhook.
Step 3: Choose how deliveries are authenticated
- HMAC (recommended, `authMethod: 2`): each delivery has a
Roxcustody-Signature header of the form t=<unix time>,v1=<signature>. Compute HMAC-SHA256(secret, "<t>.<raw request body>") in hex and compare it with v1 using a constant-time comparison. Reject the request if they differ, or if t is more than a few minutes old. Your secret is never sent. It must be at least 16 characters. - Secret header (legacy, `authMethod: 1`, default): your secret is sent as-is in the
rox-auth-secret header. Compare it with your stored secret.
Step 4: Choose events and retries
Call Create Webhook Events (POST /vaults/create-webhook-events/{id}, where id is the webhook id returned in Step 2) with the events you want, or [-1] for all events available to your vault type. Set:
- Retry Count: how many times a failed delivery is retried (1 to 10)
- Retry Period: time between retries:
1-minute, 5-minute, 15-minute, 30-minute, 1-hour, 2-hour, 3-hour, 4-hour or 5-hour
Change the list later with Update Webhook Events. Which events you can receive depends on the vault type: for example fiat events only exist in fiat vaults.
Step 5: Handle deliveries
Every delivery body contains event (the event name, for example completed_transaction) and vaultId, plus the related object (transaction, order, fiatTransaction, …, see the examples below). A delivery that fails (non-2xx answer or no answer within 10 seconds) is retried according to your retry settings, so the same event can arrive more than once: use the webhook-id header to ignore duplicates.
ℹVerify every delivery before processing it: check the Roxcustody-Signature header (HMAC) or the rox-auth-secret header (legacy), depending on the authMethod you chose.
Webhook Headers
When receiving webhook events, your server will receive the following headers:
| Header | Description |
|---|
Roxcustody-Signature | HMAC authentication only: t=<unix time>,v1=<HMAC-SHA256(secret, "t.body")> |
rox-auth-secret | Secret-header authentication only: your configured secret |
webhook-id | Unique id of the event, identical on every retry: use it to ignore duplicates |
subdomain | The corporate subdomain |
vault-id | The vault ID associated with the webhook event |
Event Types
Rox Custody fires events across the categories below. You can subscribe to all categories or only the ones relevant to your integration.
Wallet Events
| Event | Description |
|---|
sync_vault_wallets | Fires when vault wallets are synchronized with the system. |
sync_client_wallets | Fires when client wallets are synchronized with the system. |
| { |
| "event": "sync_client_wallets", |
| "vaultId": 22, |
| "vaultWallets": [ |
| { |
| "id": 3017, |
| "type": "CLIENT", |
| "asset": { |
| "id": 2000, |
| "logo": "https://assets.example.com/public/files/assets/base.png", |
| "name": "Sepolia Ether", |
| "type": "COIN", |
| "status": "ACTIVE", |
| "symbol": "ETH", |
| "decimals": 18, |
| "contractAddress": null |
| }, |
| "client": { |
| "id": 18, |
| "externalId": "Client1" |
| }, |
| "balance": "0", |
| "targetId": 18, |
| "publicAddress": "0xd6C963d5f2C06102eA87990457049055Ccf59430", |
| "pendingBalance": "0", |
| "transactionsCount": "0" |
| } |
| ] |
| } |
Transaction Events
| Event | Description |
|---|
create_transaction | Fires when a new transaction is created. |
broadcasted_transaction | Fires when a transaction is being broadcast to the blockchain network. |
completed_transaction | Fires when a transaction is confirmed and successfully completed. |
compliance_rule_transaction | Fires when a new compliance rule transaction is created |
rejected_transaction | Fires when a transaction is rejected by the admin. |
error_transaction | Fires when an unexpected error occurs during transaction processing. |
blockchain_rejected_transaction | Fires when a transaction is rejected by the blockchain network. |
cancel_transaction | Fires when a transaction is cancelled. |
| { |
| "event": "completed_transaction", |
| "vaultId": 22, |
| "transaction": { |
| "id": "423", |
| "fees": "0.000009292470526579", |
| "note": null, |
| "type": "Outgoing", |
| "amount": "1e-11", |
| "client": { |
| "id": 18, |
| "externalId": "Client1" |
| }, |
| "markup": "0 ETH", |
| "status": "COMPLETED", |
| "parentId": null, |
| "walletId": "3017", |
| "coinSymbol": "ETH", |
| "callMethod": null, |
| "dollarAmount": "0.00000004422030000000", |
| "errorMessage": null, |
| "senderAddress": "0xd6C963d5f2C06102eA87990457049055Ccf59430", |
| "encodedPayload": null, |
| "statusChangedAt": "2025-08-26T09:04:31.000Z", |
| "receiverAddress": "0x22D5Dc46AfF8A9733DEAd29D81Bc982DD0e90BeB", |
| "transactionHash": "0x16d07234a377915daf28172b50a993ff390b5167b928d581a620d79848d5fcd8", |
| "feesDollarAmount": "0.04109158344264813537", |
| "paymentPolicyType": "api", |
| "gasStationCategoryWalletId": "14" |
| } |
| } |
Assets Events
| Event | Description |
|---|
add_asset | Fires when a new asset is added to a vault. |
activate_asset | Fires when an asset is activated and made available for use. |
deactivate_asset | Fires when an asset is deactivated and becomes unavailable. |
hold_asset | Fires when an asset is placed on hold or reactivated by a corporate admin or Roxcustody super admin. |
| { |
| "event": "deactivate_asset", |
| "assets": [ |
| { |
| "id": 2000, |
| "logo": "https://assets.example.com/public/files/assets/base.png", |
| "name": "Sepolia Ether", |
| "type": "COIN", |
| "status": "ACTIVE", |
| "symbol": "ETH", |
| "network": { |
| "id": 23, |
| "logo": "https://assets.example.com/public/files/assets/base.png", |
| "name": "Base Sepolia", |
| "type": "PUBLIC", |
| "chain": { |
| "id": 84532, |
| "name": "Base Sepolia", |
| "rpcUrls": { |
| "default": { |
| "http": [ |
| "https://sepolia.base.org" |
| ] |
| } |
| }, |
| "testnet": true, |
| "blockExplorers": { |
| "default": { |
| "url": "https://sepolia.basescan.org", |
| "name": "Basescan", |
| "apiUrl": "https://api-sepolia.basescan.org/api" |
| } |
| }, |
| "nativeCurrency": { |
| "name": "Sepolia Ether", |
| "symbol": "ETH", |
| "decimals": 18 |
| } |
| }, |
| "status": "ACTIVE", |
| "symbol": "ETH", |
| "category": "EVM", |
| "isSwappable": false |
| }, |
| "decimals": 18, |
| "contractAddress": null |
| } |
| ], |
| "vaultId": 22 |
| } |
Network Events
| Event | Description |
|---|
hold_network | Fires when a blockchain network is placed on hold or reactivated by a corporate admin or Roxcustody super admin. |
activate_network | Fires when a blockchain network is reactivated. |
| { |
| "event": "hold_network", |
| "network": { |
| "id": 23, |
| "logo": "https://assets.example.com/public/files/assets/base.png", |
| "name": "Base Sepolia", |
| "type": "PUBLIC", |
| "chain": { |
| "id": 84532, |
| "name": "Base Sepolia", |
| "rpcUrls": { |
| "default": { |
| "http": [ |
| "https://sepolia.base.org" |
| ] |
| } |
| }, |
| "testnet": true, |
| "blockExplorers": { |
| "default": { |
| "url": "https://sepolia.basescan.org", |
| "name": "Basescan", |
| "apiUrl": "https://api-sepolia.basescan.org/api" |
| } |
| }, |
| "nativeCurrency": { |
| "name": "Sepolia Ether", |
| "symbol": "ETH", |
| "decimals": 18 |
| } |
| }, |
| "status": "HOLD", |
| "symbol": "ETH", |
| "category": "EVM", |
| "isSwappable": false |
| }, |
| "vaultId": 22 |
| } |
Token Events
| Event | Description |
|---|
token_created_with_asset | Fires when a new security token is created. |
| { |
| "event": "token_created_with_asset", |
| "vaultId": 22, |
| "token": { |
| "id": 123, |
| "name": "My Security Token", |
| "symbol": "MST", |
| "type": "TOKEN", |
| "network": { |
| "id": 23, |
| "name": "Base Sepolia", |
| "symbol": "ETH", |
| "category": "EVM" |
| }, |
| "vault": { |
| "id": 22, |
| "name": "My Vault" |
| } |
| } |
| } |
Crypto Payment Order Events
| Event | Description |
|---|
paid_payment_vault_order | Fires when a crypto payment order is marked as paid. |
| { |
| "event": "paid_payment_vault_order", |
| "order": { |
| "id": "01KDTERRXSM230ANGSNYJZGWNF", |
| "email": null, |
| "vault": { |
| "photo": null, |
| "fiatCurrencyDetails": { |
| "id": 5, |
| "name": "US Dollar", |
| "symbol": "$", |
| "pricingId": "usd" |
| } |
| }, |
| "status": "PAID", |
| "wallet": { |
| "id": 89, |
| "type": "ORDER", |
| "asset": { |
| "id": 3, |
| "logo": "https://api-admin.roxcustody.io/public/files/assets/aave.png", |
| "name": "Aave", |
| "type": "TOKEN", |
| "status": "ACTIVE", |
| "symbol": "aave", |
| "network": { |
| "id": 1, |
| "logo": "https://api-admin.roxcustody.io/public/files/assets/ethereum.png", |
| "name": "Ethereum", |
| "type": "PUBLIC", |
| "chain": { |
| "id": 1, |
| "name": "Ethereum", |
| "rpcUrls": { |
| "default": { |
| "http": [ |
| "https://ethereum-rpc.publicnode.com", |
| "https://eth.llamarpc.com" |
| ] |
| } |
| }, |
| "blockExplorers": { |
| "default": { |
| "url": "https://etherscan.io", |
| "name": "Etherscan", |
| "apiUrl": "https://api.etherscan.io/api" |
| } |
| }, |
| "nativeCurrency": { |
| "name": "Ether", |
| "symbol": "ETH", |
| "decimals": 18 |
| } |
| }, |
| "status": "ACTIVE", |
| "symbol": "ETH", |
| "category": "EVM", |
| "isSwappable": true |
| }, |
| "decimals": 18, |
| "contractAddress": null |
| }, |
| "balance": "0", |
| "protocol": 0, |
| "targetId": "45", |
| "publicAddress": "0x358c06c4b8e7A4B26C5016678f33Be45ab95eB89", |
| "pendingBalance": "0", |
| "transactionsCount": "0" |
| }, |
| "balance": "0", |
| "vaultId": 13, |
| "globalId": "01KDTERRXS9C608SXM91NV1MQC", |
| "itemName": null, |
| "walletId": "89", |
| "createdAt": "2025-12-31T13:00:07.767Z", |
| "updatedAt": "2025-12-31T13:02:47.000Z", |
| "clientName": null, |
| "expiration": "2025-12-31T16:02:47.000Z", |
| "paymentLink": "roxcustody.com/orders/01KDTERRXS9C608SXM91NV1MQC", |
| "amountInFiat": "25.50000000000000000000", |
| "transactions": [], |
| "amountInAsset": "0.171566978402745072", |
| "amountInDollar": "25.50000000000000000000", |
| "amountToBeCollected": "0", |
| "expirationWithTolerance": "2025-12-31T16:02:47.000Z" |
| }, |
| "vaultId": 13 |
| } |
Fiat Transaction Events
| Event | Description |
|---|
fiat_transaction_created | Fires when a fiat transaction (deposit, refund or payout) is created. |
fiat_transaction_completed | Fires when a fiat transaction is completed. |
fiat_transaction_failed | Fires when a fiat transaction fails. |
fiat_refund_created | Fires when a fiat refund is created. |
| { |
| "event": "fiat_transaction_completed", |
| "vaultId": 31, |
| "fiatTransaction": { |
| "id": 5120, |
| "fiatAccountId": 77, |
| "parentId": null, |
| "vaultId": 31, |
| "currencyCode": "SAR", |
| "rrn": "512301234567", |
| "externalTransactionId": "pay_8f2c1d", |
| "processedAt": "2026-11-09T10:22:11.000Z", |
| "createdAt": "2026-11-09T10:21:40.000Z", |
| "updatedAt": "2026-11-09T10:22:11.000Z", |
| "type": "DEPOSIT", |
| "status": "SUCCESS", |
| "brandName": "MADA", |
| "amount": "150", |
| "fees": "2.25", |
| "refundingStatus": "REFUNDABLE", |
| "paymentLinkId": "pl_01KDTF3" |
| } |
| } |
Fiat Payment Order Events
| Event | Description |
|---|
fiat_payment_vault_order_paid | Fires when a fiat payment order is paid. |
fiat_payment_vault_order_refunded | Fires when a fiat payment order is refunded. |
| { |
| "event": "fiat_payment_vault_order_paid", |
| "vaultId": 31, |
| "fiatPaymentVaultOrder": { |
| "id": "01KDTF3QZ8M2", |
| "clientName": "Sara Ahmed", |
| "itemName": "Annual plan", |
| "email": "sara@example.com", |
| "expiration": "2026-11-09T11:21:40.000Z", |
| "createdAt": "2026-11-09T10:21:40.000Z", |
| "updatedAt": "2026-11-09T10:22:11.000Z", |
| "amountInDollar": "40", |
| "amountInFiat": "150", |
| "vaultId": 31, |
| "status": "PAID" |
| } |
| } |
By subscribing to these events, you can stay updated in real time about your vault's assets, transactions, and wallets.
What's next?