Ctrl+K

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

  • cURL
  • JavaScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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
}'
Step Result
  • JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "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

  • cURL
1
2
3
4
5
6
7
8
9
10
11
12
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
  • JSON
1
2
3
4
{
  "webhookId": "wh119ecd15a4adf811f8f552fde21b9d819b4dc9a7f04c51513395816703c73511",
  "isValid": true
}

3. (Optional) Simulate Block Webhook

Endpoint: Simulate Block Webhook

  • cURL
1
2
3
4
5
6
7
8
9
10
11
12
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
  • JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "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