Create Wallet Webhooks

Create wallet webhooks to receive HTTP callbacks when wallet events occur. See the Guide.

Create a wallet webhook that notifies you whenever a specified wallet event occurs. The example creates a transfer type webhook that triggers on transfers into or out of a wallet. Wallets can have up to 10 webhooks of each wallet-webhook type. You can optionally include custom HTTP headers and configure listenToFailureStates.

Prerequisites:
- Get Started
- Create Wallets
- If you want to verify webhook notifications, ensure your enterprise has a webhook secret (see Create Webhook Secret).
API Reference
You can verify the webhook notification is legitimate by passing the payload you received in the prior step as a JSON string with your webhook secret (created with the Create webhook secret endpoint).

API Reference
You can simulate your wallet webhook with real data from the prior step or with placeholder data. Pass a transfer ID to trigger the simulation.

API Reference

// 1. Create Wallet Webhooks
export COIN="<ASSET_ID>"
export WALLET_ID="<YOUR_WALLET_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export URL="<YOUR_WEBHOOK_URL>"
export LABEL="<YOUR_WEBHOOK_NAME>"

curl -X POST \
  https://app.bitgo-test.com/api/v2/$COIN/wallet/$WALLET_ID/webhooks \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "type": "transfer",
    "url": "'"$URL"'",
    "label": "'"$LABEL"'",
    "listenToFailureStates": true,
    "customHttpHeaders": {
        "property1": "string",
        "property2": "string"
    }
  }'
// 2. (Optional) Verify Webhook Notification
export WEBHOOK_ID="<YOUR_WEBHOOK_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export SIGNATURE="<YOUR_WEBHOOK_SECRET>" # Created using the Create webhook secret endpoint
export PAYLOAD="<YOUR_PAYLOAD>" # JSON payload as a string that you received in the prior step

curl -X POST "https://app.bitgo-test.com/api/v2/webhook/$WEBHOOK_ID/verify" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "signature": "'"$SIGNATURE"'",
    "notificationPayload": "'"$PAYLOAD"'"
  }'
// 3. (Optional) Simulate Wallet Webhook
export COIN="<ASSET_ID>"
export WALLET_ID="<YOUR_WALLET_ID>"
export WEBHOOK_ID="<YOUR_WEBHOOK_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export TRANSFER_ID="<YOUR_TRANSFER_TOKEN>"

curl -X POST "https://app.bitgo-test.com/api/v2/$COIN/wallet/$WALLET_ID/webhooks/$WEBHOOK_ID/simulate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
  -d '{
  "transferId": "'"$TRANSFER_ID"'"
}'

// 1. Create Wallet Webhooks
const BitGo = require('bitgo');
const bitgo = new BitGo.BitGo({
  env: 'test',
  accessToken: process.env.TEST_ACCESS_TOKEN
});
bitgo.coin('tbtc4').wallets().get({
  id: '<wallet_id>'
}).then((wallet) => {
  wallet.addWebhook({
    type: 'transfer',
    allToken: false,
    url: 'http://your.server.com/webhook',
    label: '<your_webhook_label>',
    nnumConfirmations: 6,
    listenToFailureStates: true
  })
});
// 2. (Optional) Verify Webhook Notification
// Use the REST API for this step (see cURL tab)
// 3. (Optional) Simulate Wallet Webhook
// Use the REST API for this step (see cURL tab)

Response

// 1. Create Wallet Webhooks Response
{
  "id": "6853113bd6d99d1109391bc98a0dbfd5",
  "label": "my-btc-transfer-webhook",
  "created": "2025-06-18T19:19:23.127Z",
  "scope": "wallet",
  "walletId": "67536a92b294f87c998ea39f85a6bdc7",
  "coin": "tbtc4",
  "type": "transfer",
  "url": "https://webhook.site/f74addc1-c40a-4fce-879a-2d92b8d491c5",
  "version": 2,
  "state": "active",
  "successiveFailedAttempts": 0,
  "listenToFailureStates": true,
  "txRequestStates": [],
  "txRequestTransactionStates": []
}

// 2. (Optional) Verify Webhook Notification Response
{
  "webhookId": "wh119ecd15a4adf811f8f552fde21b9d819b4dc9a7f04c51513395816703c73511",
  "isValid": true
}

// 3. (Optional) Simulate Wallet Webhook Response
{
    "webhookNotifications": [
        {
            "id": "6853262b9da229cea98569ce71fc060e",
            "type": "transfer",
            "wallet": "62c5b5c9d0ece30007cec9616ff29edc",
            "enterprise": "62c5ae8174ac860007aff138a2d74df7",
            "organization": "62c5ae8174ac860007aff1555ffb960d",
            "url": "https://webhook.site/f74addc1-c40a-4fce-879a-2d92b8d491c5",
            "hash": "db924f4cf2347ac5a6b464d3e8dc4a20cffc117eb29f4460645fbc34de171bfb",
            "coin": "tbtc4",
            "transfer": "68531ea4e3669330070c95e454f5b366",
            "state": "new",
            "simulation": true,
            "retries": 0,
            "webhook": "68531e154d28af627819bd3e183a930e",
            "updatedAt": "2025-06-18T20:48:43.525Z",
            "version": 2,
            "idempotencyKey": "e3094fa873a8e5b5"
        }
    ]
}