Create Block Webhooks

Create block webhooks to receive HTTP callbacks when on-chain block events occur. See the Guide.

  1. Create a webhook that notifies you whenever a block receives a specified number of confirmations. The example creates a block type webhook that triggers after 6 confirmations.

    Prerequisites:

    API Reference

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

  3. You can simulate your block webhook to test the notification delivery. Pass a block ID (accessible on a blockchain explorer) to trigger the simulation.

    API Reference

// 1. Create Block Webhooks
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
}'
// 2. (Optional) Verify Block 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 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"'"
}'
Response
// 1. Create Block Webhooks Response
{
  "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 Response
{
  "webhookId": "wh119ecd15a4adf811f8f552fde21b9d819b4dc9a7f04c51513395816703c73511",
  "isValid": true
}

// 3. (Optional) Simulate Block Webhook Response
{
    "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
        }
    ]
}