v1 .2025-09-23
Jump to
Ctrl
+
/

Webhooks

Overview

Webhooks, or callbacks, are POST requests sent from Vaultody to your specified URL when subscribed events occur. This mechanism allows real-time notifications for events such as transaction requests, approvals, rejections, and incoming transactions.

Setting Up Webhooks

  1. Navigate to Developers Section: In the Dashboard, go to the Developers menu and select Webhooks.
  2. Add a New Webhook Endpoint: Click the "Add Endpoint" button and enter your desired callback URL.
  3. Authenticate the Request: Set a secret for your webhook to ensure secure communication.
  4. Select Events: Choose the events you wish to subscribe to for notifications.

Example Payloads

Transaction Request

{
  "walletId": "64463ff167ecf9000707b052",
  "webhookId": "65b2633879435ab2f30727ff",
  "idempotencyKey": "uniqueKey",
  "apiVersion": "2025-09-23",
  "data": {
    "event": "TRANSACTION_REQUEST",
    "item": {
      "blockchain": "tron",
      "network": "nile",
      "requestId": "65e89fd7e7684b8228dec633"
    }
  }
}

Transaction Approved

{
  "walletId": "64463ff167ecf9000707b052",
  "webhookId": "65b2633879435ab2f30727ff",
  "idempotencyKey": "uniqueKey",
  "apiVersion": "2025-09-23",
  "data": {
    "event": "TRANSACTION_APPROVED",
    "item": {
      "blockchain": "tron",
      "network": "nile",
      "requestId": "65e89fd7e7684b8228dec633",
      "requiredApprovals": 1,
      "requiredRejections": 1,
      "currentApprovals": 1,
      "currentRejections": 0
    }
  }
}

Transaction Reject

{
  "walletId": "64463ff167ecf9000707b052",
  "webhookId": "65b2633879435ab2f30727ff",
  "idempotencyKey": "acb0ab432a693f604f45cfe08352b02074fa0053990f9e58140d41dfb71472db",
  "apiVersion": "2025-09-23",
  "data": {
    "event": "TRANSACTION_REJECTED",
    "item": {
      "blockchain": "tron",
      "network": "nile",
      "requestId": "65e069a6e7684b8228ff583a",
      "requiredApprovals": 1,
      "requiredRejections": 1,
      "currentApprovals": 0,
      "currentRejections": 1
    }
  }
}

Incoming Confirm Coin Transaciton

{
  "walletId": "64463ff167ecf9000707b052",
  "webhookId": "65b2633879435ab2f30727ff",
  "idempotencyKey": "c989505f082b3463a14d50f9ab785951366fd93012c9869ea1347d8f0b722ea7",
  "apiVersion": "2025-09-23",
  "data": {
    "event": "INCOMING_CONFIRMED_COIN_TX",
    "item": {
      "blockchain": "binance-smart-chain",
      "network": "testnet",
      "address": "0x6746d7d3f59c1cf062ad25bff246660297122ff2",
      "minedInBlock": {
        "height": 37959320,
        "hash": "0x8cff00dcce8c5eecd1bd42bb68b31ac126263cb819133a8e550465cf4426d711",
        "timestamp": 1708588551
      },
      "currentConfirmations": 12,
      "targetConfirmations": 12,
      "amount": "0.3",
      "unit": "BNB",
      "transactionId": "0x94405584ed8c2177094f056e7ea6d2c157f3a3e2c1585669e222c5a40d104ef6"
    }
  }
}

Incoming Confirmed Token Transaction

{
  "walletId": "64463ff167ecf9000707b052",
  "webhookId": "65b2633879435ab2f30727ff",
  "idempotencyKey": "b0c63d216889beb4f6d2154231f1becd2b7d9dbc349a6644cae839b5f35791b1",
  "apiVersion": "2025-09-23",
  "data": {
    "event": "INCOMING_CONFIRMED_TOKEN_TX",
    "item": {
      "blockchain": "tron",
      "network": "nile",
      "address": "TDGFc6pDe5q2gc9zi4p2JQHfJTXVTBw7yu",
      "minedInBlock": {
        "height": 45323934,
        "hash": "0000000002b3969e82281bb3b6d96e88e416d422faaae27a05b8522bc30c83fc",
        "timestamp": 1710924012
      },
      "currentConfirmations": 4,
      "targetConfirmations": 12,
      "tokenType": "TRC-20",
      "transactionId": "a6f8225d5a905fc236e5d85d88f77d127d48e80bb456042853c8ed6210182f4f",
      "token": {
        "tokenName": "Tether USD",
        "tokenSymbol": "USDT",
        "decimals": 6,
        "tokensAmount": "50000",
        "contract": "TXLAQ63Xg1NAzckPwKHvzw7CSEmLMEqcdj"
      }
    }
  }
}

Incoming Confirmed Internal Transaction

{
  "walletId": "6577004524a7d60007f63383",
  "webhookId": "65faf3fba2d408b0ffc9fe3d",
  "idempotencyKey": "e1db8b89178b6041039d5d5b94022818370318d1a9d6efef281fa3c93c27044a",
  "apiVersion": "2025-09-23",
  "data": {
    "event": "INCOMING_CONFIRMED_INTERNAL_TX",
    "item": {
      "blockchain": "binance-smart-chain",
      "network": "testnet",
      "address": "0x81318d093ca1a3a4d33970361f5937b1f3be2265",
      "minedInBlock": {
        "height": 38793161,
        "hash": "0x1488f39e69d17cdade73cb3b110e9811c7e2a186afac7cdba3f33806913e40c5",
        "timestamp": 1711091362
      },
      "currentConfirmations": 8,
      "targetConfirmations": 12,
      "amount": "0.000001",
      "unit": "BNB",
      "parentTransactionId": "0x354a445437b6795874273d9e578473fceb8e70049c42bf02f14103f4ae871211",
      "operationId": "call"
    }
  }
}

Incoming Mined Transaction

{
  "walletId": "64463ff167ecf9000707b052",
  "webhookId": "65b2633879435ab2f30727ff",
  "idempotencyKey": "4a159a6f79f0676d251e06eaee0491f7c20ad38987227c793482d4a4b2dbac18",
  "apiVersion": "2025-09-23",
  "data": {
    "event": "INCOMING_MINED_TX",
    "item": {
      "blockchain": "tron",
      "network": "nile",
      "address": "TDGFc6pDe5q2gc9zi4p2JQHfJTXVTBw7yu",
      "minedInBlock": {
        "height": 45323934,
        "hash": "0000000002b3969e82281bb3b6d96e88e416d422faaae27a05b8522bc30c83fc",
        "timestamp": 1710924012
      },
      "direction": "incoming",
      "currentConfirmations": 1,
      "targetConfirmations": 12,
      "tokenType": "TRC-20",
      "transactionId": "a6f8225d5a905fc236e5d85d88f77d127d48e80bb456042853c8ed6210182f4f",
      "token": {
        "amount": "50000",
        "contractAddress": "TXLAQ63Xg1NAzckPwKHvzw7CSEmLMEqcdj",
        "symbol": "USDT",
        "name": "Tether USD",
        "decimals": 6
      }
    }
  }
}

Outgoing Transaction Failed

{
  "apiVersion": "2025-09-23",
  "webhookId": "64dcca5c3c61607960b5e02d",
  "idempotencyKey": "e14ab5620c3559334888f122eeef082dc999743f4e0373fedc29a0e2c3383d27",
  "data": {
    "event": "OUTGOING_FAILED",
    "item": {
      "blockchain": "xrp",
      "currentApprovals": 1,
      "currentRejections": 0,
      "failedReason": "TO_ADDRESS_MUST_BE_DIFFERENT_FROM_SOURCE_ADDRESS",
      "network": "testnet",
      "requestId": "64dccace225244d7f76c2b96",
      "requiredApprovals": 1,
      "requiredRejections": 1
    }
  }
}

Outgoing Transaction Mined

{
  "walletId": "64463ff167ecf9000707b052",
  "webhookId": "65b2633879435ab2f30727ff",
  "idempotencyKey": "23237ea1af1689844e6b4779318a42f042aee630be5a4ebfac98b71521f2c578",
  "apiVersion": "2025-09-23",
  "data": {
    "event": "OUTGOING_MINED",
    "item": {
      "blockchain": "tron",
      "network": "nile",
      "requestId": "65e89fd7e7684b8228dec633",
      "requiredApprovals": 1,
      "requiredRejections": 1,
      "currentApprovals": 1,
      "currentRejections": 0,
      "transactionId": "f0509c32db54a723b2934f36964ad67f8ababd2944438c4c4c7ebd140b95f8de"
    }
  }
}

Outgoing Transaction Broadcasted

{
  "walletId": "64463ff167ecf9000707b052",
  "webhookId": "65b2633879435ab2f30727ff",
  "idempotencyKey": "4cd1ad4ca3e0698017d1e520c93a88142dd122acb975a1786a20f8818924455b",
  "apiVersion": "2025-09-23",
  "data": {
    "event": "TRANSACTION_BROADCASTED",
    "item": {
      "blockchain": "tron",
      "network": "nile",
      "requestId": "65e89fd7e7684b8228dec633",
      "requiredApprovals": 1,
      "requiredRejections": 1,
      "currentApprovals": 1,
      "currentRejections": 0,
      "transactionId": "f0509c32db54a723b2934f36964ad67f8ababd2944438c4c4c7ebd140b95f8de"
    }
  }
}

Customer’s Signing Secret

The customer’s request can include data on the event they want to subscribe for and has the option to also have a Signing Secret. This parameter is a required security measure for the benefit of the customer. The Signing Secret can only be generated by the customer. It is used to create a unique hash string in the x-signature response header in the callback request sent from Vaultody when the event occurs.

The Signing Secret, and thus the x-signature, are set up per event subscription, not per single callback. Hence, the customer only needs to set up the Signing Secret once when creating the event. They can use a single Signing Secret for all subscriptions, or different ones for each subscription. The security is effective enough even with just one common Signing Secret.

Callback Signature

The x-signature is provided in the header of the callback and represents a unique hash derived from all the information included in the callback about the event (which must be JSON encoded) and the customer’s Signing Secret.

For this purpose, HMAC_SHA256 is used. It stands for Hash-based message authentication code, and along with its cryptographic hash function SHA256, it represents higher security than any other authentication code.

The cryptographic strength of the HMAC depends upon the size of the Signing Secret that has been used. The most common attack against HMACs is brute force to uncover the secret key. HMACs are substantially less affected by collisions than their underlying hashing algorithms alone.

When the customer receives the callback request from Vaultody, they can first check the x-signature before processing the request. By using their Signing Secret, which only they would know, together with the information from the callback, they can generate a hash and compare it to the x-signature hash that the Vaultody server has returned. They must match, which only then would authenticate Vaultody as the true sender.

After authentication of the callback, the customer can then proceed to processing it. If the authentication with the x-signature fails, then the customer must ignore it as someone else is sending it.

Need Help?

For additional support, visit our Help Center.

Was this page helpful?
Yes
No
Powered by

On this page