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:

Type	Description
Address confirmation	Triggers when a new wallet address initializes. This is only applicable for ETH and XRP.
Low fee	Triggers when the average fee on a blockchain drops below a configurable threshold set on a wallet.
Pending approval	Triggers when there's a wallet event that requires approval. For example, pending approval state updates, policy changes, sending transactions, or user changes.
Transaction	Triggers when there's a transaction recorded on chain. Returns the transaction hash.
Transfer	Triggers 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.

Wallet-Level Pending Approval Webhooks

Bitgo offers the following webhooks for wallet-level pending approvals:

Type	Description
User Change Request	Adds or removes a user from a wallet.
Transaction Request	Approves a transaction (sent via the /send or /initiate APIs) that violates wallet policy.
Transaction Request Full	Approves a transaction (sent via the Transaction Request APIs) that violates wallet policy.
Policy Rule Request	Updates a policy.
Update Approvals Required Request	Updates the number of approvers required for a wallet.

Enterprise-Level Pending Approval Webhooks

BitGo offers the following webhooks for enterprise-level pending approvals:

Type	Description
User Change Request	Adds or removes a user from a wallet.
Transaction Request	Approves a transaction (sent via the /send or /initiate APIs) that violates wallet policy.
Policy Rule Request	Updates a policy.
Update Approvals Required Request	Updates the number of approvers required for a wallet.
Update Enterprise Request	Adds or removes a user from an enterprise.

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

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

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.

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.

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:

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"
  }
]
}

Kits

Concepts

JavaScript SDK

BitGo Express

Create

Transact

Unspents

Trade

Stake

View

Users

Policies

Manage

Clients

Partners

Create Webhooks

Overview

Retries

Suspensions

Webhook Types

Wallet Webhooks

Wallet-Level Pending Approval Webhooks

Enterprise-Level Pending Approval Webhooks

Block Webhooks

Create Webhooks

Wallet Webhooks

Step Result

Block Webhooks

Step Result

Webhook Policies

Deny Policy

Get Approval Policy

Sample Webhook Body

See Also