Create Webhooks

Overview

You can set up webhooks to programmatically receive callbacks or notifications from BitGo when specific events occur. For example, you can attach webhooks to wallets to receive transaction notifications or to blocks to receive block notifications.

Note: 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.

To ensure streamlined operations, it's important that you configure your application to succeed even if:

• You encounter transient network errors.
• You receive the same webhook twice, due improper acknowledgement.

Retries

BitGo servers make POST HTTP requests to the URL defined in a JSON payload. If we don't receive a successful HTTP 200 OK response, we attempt to retry the webhook with an increasing delay between each retry. After the original attempt, BitGo will make up to 7 additional attempts. Retry intervals are as follows:

1, 5, 10, 30, 60, 120, 240 minutes

Suspensions

BitGo suspends sending notifications when either of the following occur for a webhook:

• At least 100 notification failures within 1 week.
• At least 500 notification failures over the lifetime.

If BitGo suspends a webhook, you must delete the suspended webhook and create a new one.

Webhook Types

Wallet Webhooks

BitGo offers the following webhooks for wallets:

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 Webhooks

BitGo offers the following webhooks for blocks:

• Block - Triggers when there's a new block on the coin network.
• Wallet confirmation - Triggers when a wallet initializes.

Create Webhooks

Wallet Webhooks

Copy code block
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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
  })
});

For more examples, see our GitHub repository and API Reference.

Step Result

Copy code block
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "allToken": false,
  "id": "59cd72485007a239fb00282ed480da1f",
  "label": "Test Webhook",
  "created": "2018-05-05T19:46:22.019Z",
  "coin": "btc",
  "type": "transfer",
  "url": "https://your.server.com/webhook",
  "version": 2,
  "numConfirmations": 6,
  "state": "active",
  "lastAttempt": "2018-05-05T19:46:22.019Z",
  "failingSince": "2018-05-05T19:46:22.019Z",
  "successiveFailedAttempts": 0
}

Block Webhooks

Copy code block
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
//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

Copy code block
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "type": "transfer",
  "userId": "59cd72485007a239fb00282ed480da1f",
  "id": "59cd72485007a239fb00282ed480da1f",
  "label": "Test Webhook",
  "created": "2018-05-05T19:46:22.019Z",
  "coin": "btc",
  "url": "https://your.server.com/webhook",
  "version": 2,
  "numConfirmations": 6,
  "state": "active",
  "lastAttempt": "2018-05-05T19:46:22.019Z",
  "failingSince": "2018-05-05T19:46:22.019Z",
  "successiveFailedAttempts": 0
}

For more examples, see our GitHub repository and API Reference.

Webhook Signature

BitGo strengthens the security of webhooks by using secret tokens and notification signatures, allowing you to verify the authenticity of webhook notifications.

First, look for the x-signature-sha256 header in the webhook notification you receive.

BitGo generates a unique secret token that you can initiate or rotate through using the Create webhook secret endpoint. This token is specific to each individual enterprise or organization, particularly for B2B2C clients. It serves as the webhook signing key.

When sending a webhook, this key is utilized in conjunction with an HMAC hashing algorithm, SHA256, to create a cryptographic hash of the webhook payload. This hash acts as the unique signature for the webhook.

You can use the Verify Webhook NotificationAPI endpoint to verify webhook notifications you receive.

Webhook Idempotency Key

BitGo also supports idempotency by allowing you to include a unique key, referred to as an idempotency-key, in the request header. This helps you avoid processing duplicate webhook notifications.

See Also

• API Reference: Add Wallet Webhook
• API Reference: Create webhook secret
• API Reference: Verify Webhook Notification
• For testing purposes, BitGo recommends using Webhook.site to receive webhooks and control the response codes.