Ctrl+K

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.

Before you process a webhook notification, we recommend you verify the information sent in it by fetching the transfer or block data from BitGo. Also, ensure your application can 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.

Webhook Types

Wallet Webhooks

BitGo offers the following webhooks for wallets:

TypeDescription
Address confirmationTriggers when a new wallet address initializes. This is only applicable for ETH and XRP.
Low feeTriggers when the average fee on a blockchain drops below a configurable threshold set on a wallet.
Pending approvalTriggers when there's a wallet event that requires approval. For example, pending approval updates, policy changes, sending transactions, or user changes.
TransactionTriggers when there's a transaction recorded on chain. Returns the transaction hash.
TransferTriggers when there's a transfer into or out of a wallet.

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

  • SDK
  • API
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('tbtc').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
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

  • SDK
  • API
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. tbtc
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
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 Policies

Webhook policies allow you to implement your own unique policies using business logic in your own systems. Each time a transaction initiates, BitGo makes a request that includes information about the transaction to the URL defined in the webhook policy. After you receive a webhook request, you can respond with one of the following:

  • A 200 response to continue processing.
  • A non-200 response to trigger the action defined in the policy rule.

Useful actions are:

  • deny - Blocks the transaction from further processing.
  • getApproval - Requires the transaction to get approvals from a defined list of users.

Deny Policy

Creates a webhook-policy rule that denies transactions when a non-200 response returns.

  • API
1
2
3
4
5
6
7
8
9
10
11
12
POST /api/v2/{coin}/wallet/{walletId}/policy/rule

{
  "id": "user-provided-id-for-this-rule",
  "type": "webhook",
  "condition": {
    "url": "https://webhook.site/25f3dea6-8a4c-455f-99c1-a538d345f93f"
  },
  "action": {
    "type": "deny"
  }
}

Get Approval Policy

Creates a webhook-policy rule that requires approvals from 1 or more users when a non-200 response returns.

  • API
1
2
3
4
5
6
7
8
9
10
11
12
13
14
POST /api/v2/{coin}/wallet/{walletId}/policy/rule

{
  "id": "user-provided-id-for-this-rule",
  "type": "webhook",
  "condition": {
    "url": "https://webhook.site/25f3dea6-8a4c-455f-99c1-a538d345f93f"
  },
  "action": {
    "type": "getApproval",
    "approvalsRequired": 1,
    "userIds": ["5db726e0ad7c022100a26f1aae38cae7"]
  }
}

Sample Webhook Body

The following is a sample payload that's sent to the webhook URL, defined in the webhook-policy rule, each time a transaction initiates:

  • API
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
"walletId": "5fb34d22bbd86300328d60813fcd7906",
"ruleId": "user-provided-id-for-this-rule",
"type": "webhook",
"spendAmount": "200000",
"approvalCount": 0,
"halfSigned": {
  "txHex": "01000000000101c92fd8e311fe62c477bddd7fd6ab7b38ad9a37ed98f3963f29aaba878f82f4ed0100000023220020b23d4416444ff1bdd5c1fc99202f68a4dc98436687382b43791121a941516be8ffffffff02400d03000000000017a9144f83dee62ec99972e5a2d54ac84bf8fa02f210cc87856d0c000000000017a914b89f2281524e035c1edcc5247f1906a33c66f85b87050048304502210084c3117cd96b2046eb95397dcdc892fb08307d9f2cc19b0a9d8714e38e27adcb022013974858a88a0e713e6dcf24ff690cff4500067becccfff1ba91016184d1b84601000069522103aaf369386f631a3a53c02ff0071fe526b6355dc0c672a221e40ddda49fcdfae02102f2f3f3c707bf542b884e89bb41d75e350723445d658872542642785f4f030495210258cdbcbdcb8e450bfba6486108e14d6ce8f3db69f13059c2122746bb09cfbcd853aeb4df1c00"
},
"outputs": [
  {
    "address": "2MzVfLyXXXjLBQdA6D8gY6DM9hR1XdJkZjR",
    "value": 200000,
    "wallet": "5ef52bdc4ba8da93002ae504e3fa89d0"
  },
  {
    "address": "2NA5QxTc2rDi18fgWrZCNoaa9ktp5ucWeFC",
    "value": 814469,
    "wallet": "5fb34d22bbd86300328d60813fcd7906"
  }
]
}

See Also