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 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.
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" } ] }
See Also
- API Reference: Add Wallet Webhook
- For testing purposes, BitGo recommends using Webhook.site to receive webhooks and control the response codes.