Guides
Start typing to search…

Create Block Webhooks

Overview

You can create block webhooks to receive an HTTP callback from BitGo to a specified URL when specific on-chain events occur.

Note: An unconfirmed webhook notification doesn't trigger if a transaction is confirmed on chain immediately after it's sent, or if it's a Replace-by-fee (RBF) transaction.

Block Webhook Types

BitGo offers the following types of webhooks for blocks:

TypeTriggers When
blockA new block confirms on chain.
wallet_confirmationA wallet initializes on chain.

Prerequisites

1. Create Block Webhooks

The following example creates a webhook that notifies you whenever a block receives 6 confirmations.

Endpoint: Add Wallet Webhook

export COIN="<ASSET_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/webhooks \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "type": "block",
    "url": "'"$URL"'",
    "label": "'"$LABEL"'",
    "numConfirmations": 6
}'
//Add a new block webhook when a new block is seen on the network or when a wallet is initialized of a given user defined coin.
import { BitGo } from 'bitgo';

// change this to env: 'production' when you are ready for production
const bitgo = new BitGo({ env: 'test' });

// set your access token here
const accessToken = '';

// Set the coin type of an active wallet in your BitGo account
// e.g. tbtc4
const network = '';

// Set the url you would like to receive notifications at
// e.g. https://domain.com/callback
const callbackUrl = '';

// Set notification trigger type
// e.g. 'block' | 'wallet_confirmation'
const type = '';

// Add a label to your webhook (optional)
const label = '';

// Add a minimum number of confirmations before the webhook is triggered (optional)
// Defaults to 0
const numConfirmations = 0;
async function main() {
  bitgo.authenticateWithAccessToken({ accessToken });
  const coin = bitgo.coin(network);
  const newWebhook = await coin.webhooks().add({ url: callbackUrl, type, label, numConfirmations });
  console.log('New webhook created successfully');
  console.log(newWebhook);
}
main().catch((e) => console.error(e));
Step Result
{
  "id": "68532fdcd3c9a6ca39264fcd6b80078c",
  "label": "my-block-webhook",
  "created": "2025-06-18T21:30:04.761Z",
  "userId": "62ab90e06dfda30007974f0a52a12995",
  "coin": "tbtc",
  "type": "block",
  "url": "https://webhook.site/f74addc1-c40a-4fce-879a-2d92b8d491c5",
  "version": 2,
  "numConfirmations": 6,
  "state": "active",
  "successiveFailedAttempts": 0,
  "listenToFailureStates": false,
  "txRequestStates": [],
  "txRequestTransactionStates": []
}

2. (Optional) Verify Block Notification

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).

Endpoint: 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"'"
  }'
Step Result
{
  "webhookId": "wh119ecd15a4adf811f8f552fde21b9d819b4dc9a7f04c51513395816703c73511",
  "isValid": true
}

3. (Optional) Simulate Block Webhook

Endpoint: Simulate Block Webhook

export COIN="<ASSET_ID>"
export WALLET_ID="<YOUR_WALLET_ID>"
export WEBHOOK_ID="<YOUR_WEBHOOK_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export BLOCK_ID="<BLOCK_ID>"

curl -X POST "https://app.bitgo-test.com/api/v2/$COIN/webhooks/$WEBHOOK_ID/simulate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
  -d '{
  "blockId": "'"$BLOCK_ID"'"    # Accessible on a blockchain explorer
}'
Step Result
{
    "webhookNotifications": [
        {
            "id": "685332f8c7bcf7997f149cde4acc3347",
            "type": "block",
            "url": "https://webhook.site/f74addc1-c40a-4fce-879a-2d92b8d491c5",
            "hash": "000000000000058e4811df2692686894adb547473c1268c1f1693eaa61bc003b",
            "coin": "tbtc4",
            "state": "new",
            "simulation": true,
            "retries": 0,
            "webhook": "68532fdcd3c9a6ca39264fcd6b80078c",
            "updatedAt": "2025-06-18T21:43:20.151Z",
            "version": 2
        }
    ]
}

Next

Before you process webhook notifications, BitGo strongly recommends that you verify response details by fetching the transfer or block data from BitGo. For example, if you create a transfer webhook and receive a transfer ID, pass that ID to the Get Transfer endpoint to verify the transfer details.

For more examples, see the BitGo JavaScript SDK GitHub repository.

See Also

Updated about 1 month ago