HomeDocsWebhooks
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:

HeaderDescription
Roxcustody-SignatureHMAC authentication only: t=<unix time>,v1=<HMAC-SHA256(secret, "t.body")>
rox-auth-secretSecret-header authentication only: your configured secret
webhook-idUnique id of the event, identical on every retry: use it to ignore duplicates
subdomainThe corporate subdomain
vault-idThe 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

EventDescription
sync_vault_walletsFires when vault wallets are synchronized with the system.
sync_client_walletsFires when client wallets are synchronized with the system.
Wallet Events, example payload
JSON
{
"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

EventDescription
create_transactionFires when a new transaction is created.
broadcasted_transactionFires when a transaction is being broadcast to the blockchain network.
completed_transactionFires when a transaction is confirmed and successfully completed.
compliance_rule_transactionFires when a new compliance rule transaction is created
rejected_transactionFires when a transaction is rejected by the admin.
error_transactionFires when an unexpected error occurs during transaction processing.
blockchain_rejected_transactionFires when a transaction is rejected by the blockchain network.
cancel_transactionFires when a transaction is cancelled.
Transaction Events, example payload
JSON
{
"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

EventDescription
add_assetFires when a new asset is added to a vault.
activate_assetFires when an asset is activated and made available for use.
deactivate_assetFires when an asset is deactivated and becomes unavailable.
hold_assetFires when an asset is placed on hold or reactivated by a corporate admin or Roxcustody super admin.
Assets Events, example payload
JSON
{
"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

EventDescription
hold_networkFires when a blockchain network is placed on hold or reactivated by a corporate admin or Roxcustody super admin.
activate_networkFires when a blockchain network is reactivated.
Network Events, example payload
JSON
{
"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

EventDescription
token_created_with_assetFires when a new security token is created.
Token Events, example payload
JSON
{
"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

EventDescription
paid_payment_vault_orderFires when a crypto payment order is marked as paid.
Crypto Payment Order Events, example payload
JSON
{
"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

EventDescription
fiat_transaction_createdFires when a fiat transaction (deposit, refund or payout) is created.
fiat_transaction_completedFires when a fiat transaction is completed.
fiat_transaction_failedFires when a fiat transaction fails.
fiat_refund_createdFires when a fiat refund is created.
Fiat Transaction Events, example payload
JSON
{
"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

EventDescription
fiat_payment_vault_order_paidFires when a fiat payment order is paid.
fiat_payment_vault_order_refundedFires when a fiat payment order is refunded.
Fiat Payment Order Events, example payload
JSON
{
"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?