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 22 days ago