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

To start receiving real-time updates for events to your system, follow the steps below:

---

Step 1: Access Your Corporate Dashboard

1. Navigate to your Rox Custody Corporate Dashboard using your subdomain.

   • Example: https://[your-subdomain].roxcustody.com

2. Log in with your credentials and ensure you have access to your corporate dashboard.

Step 2: Create Your Vault

Before setting up webhooks, ensure you have created a vault within the dashboard. This is a required step, as the webhook events will correspond to activities linked to your vault.

Step 3: Verify Your Website and Token

1. Input Your Server's URL: Provide the URL where you want to receive webhook events.

2. Set Your Secret Token: Enter a token of your choice. This token will be sent in the webhook request headers under the key rox-auth-secret.

3. Verify Requests on Your Server: Use the rox-auth-secret header to validate the authenticity of incoming webhook payloads on your backend server.

Step 4: Events Selection

After verification, choose the events you want to subscribe to, so you only receive updates for relevant actions.

Step 5: Test Your Webhook

You can trigger a test event from the webhooks events page to ensure your endpoint is correctly configured to receive and process webhook payloads.

Event Examples

We provide the following webhook events for your vault activities:

1. Asset Events

   • ADD_ASSET: Triggered when a new asset is added.

   • ACTIVATE_ASSET: Triggered when your vault asset is activated.

   • DEACTIVATE_ASSET: Triggered when your vault asset is deactivated.

2. Transaction Events

   • CREATE_TRANSACTION: Triggered when a transaction is initiated from RoxCustody or received from an external source.

   • REJECTED_TRANSACTION: Triggered when a transaction is rejected.

   • ERROR_TRANSACTION: Triggered when a transaction encounters an error.

   • BLOCKCHAIN_REJECTED_TRANSACTION: Triggered when the blockchain rejects a transaction.

   • COMPLETED_TRANSACTION: Triggered when a transaction is successfully completed.

3. Wallet Events

   • SYNC_VAULT_WALLETS: Triggered when new vault wallets are created.

   • SYNC_CLIENT_WALLETS: Triggered when new client wallets are created.

By subscribing to these events, you can stay updated in real time about your vault's assets, transactions, and wallets.

Payload Examples

1: Asset Event

This example represents the webhook payload for an Asset Event (e.g., add_asset):

{
  "assets": [
    {
      "id": 11257,
      "name": "Avalanche",
      "symbol": "AVAX",
      "contract_address": null,
      "network": {
        "id": 10,
        "name": "Avalanche",
        "symbol": "AVAX",
        "type": "PUBLIC",
        "status": "ACTIVE",
        "logo": "https://api-super-admin-custody-demo.roxcustody.io/public/files/biconomy-assets/avalanche.png"
      },
      "type": "COIN",
      "status": "ACTIVE",
      "logo": "https://api-super-admin-custody-demo.roxcustody.io/public/files/biconomy-assets/avalanche.png"
    }
  ],
  "event": "add_asset",
  "vaultId": 2
}

2: Transaction Event

This example represents the webhook payload for a Transaction Event (e.g., create_transaction):

{
  "transaction": {
    "id": "18",
    "amount": "0.00001000000000000000",
    "dollar_amount": "0.03873630000000000000",
    "wallet_id": "12",
    "sender_address": "0xF70C848cE6E9641e599650a3b88ED7a336b170Bf",
    "receiver_address": "0x4d817dA8f71cCcFd805EA5046811D9b3B7D03eeB",
    "encoded_payload": null,
    "note": null,
    "call_method": null,
    "error_message": null,
    "markup": "0 ETH",
    "fees": "0.00186394123420000000 ETH",
    "type": "Outgoing",
    "transaction_hash": null,
    "status": "PENDING"
  },
  "event": "create_transaction",
  "vaultId": 2
}

3: Sync Client Wallets Event

This example represents the webhook payload for the sync_client_wallets event:

{
  "vaultWallets": [
    {
      "id": 119,
      "balance": 0,
      "pending_balance": 0,
      "public_address": "0xeFbA48BFacd7841828CEF53666c99Bf586aC47fa",
      "transactions_count": "0",
      "asset": {
        "id": 2,
        "name": "Zus",
        "symbol": "zcn",
        "contract_address": "0xb9ef770b6a5e12e45983c5d80545258aa38f3b78",
        "network": {
          "id": 1,
          "name": "Ethereum",
          "symbol": "ETH",
          "type": "PUBLIC",
          "status": "ACTIVE",
          "logo": "https://api-super-admin-custody-demo.roxcustody.io/public/files/biconomy-assets/ethereum.png"
        },
        "type": "TOKEN",
        "status": "ACTIVE"
      },
      "client": {
        "id": 8
      }
    }
  ],
  "event": "sync_client_wallets",
  "vaultId": 2
}