Ctrl+K

Add wallet webhook

post/api/v2/{coin}/wallet/{walletId}/webhooks

Add a webhook that will result in an HTTP callback at the specified URL from BitGo when events are triggered. There is a limit of 10 webhooks of each type per wallet.

Types of wallet webhooks available:

  1. Transfer webhooks will fire on any transfer on the wallet.
  2. Pending approval webhooks will fire when an event triggers policy on the wallet (e.g send transaction, user change, policy change, pending approval updated).
  3. (Ripple, ETH only) Address confirmation webhooks will fire when an address has been initialized on the wallet.

Note that an unconfirmed webhook notification won't be triggered if a transaction is confirmed on chain immediately after it is sent, or if is an RBF transaction. API users are not supposed to expect 'unconfirmed' notifications in these cases.

Path Parameters

  • coinstringRequired
    A cryptocurrency or token ticker symbol.
    Example: "btc"
  • walletIdstringRequired
    Example: "59cd72485007a239fb00282ed480da1f"
    Pattern: ^[0-9a-f]{32}$

Request Body

type string required
Event type to listen to.
Allowed values: transfer transaction pendingapproval address_confirmation lowFee
Example: transfer
allToken boolean
Triggers on coin transfers and token transfers for ETH and Stellar.
Default: false
url string <uri>required
URL to fire the webhook to.
Example: http://your.server.com/webhook
label string
Label of the new webhook.
numConfirmations integer
Number of confirmations before triggering the webhook. If 0 or unspecified, requests will be sent to the callback endpoint when the transfer is first seen and when it is confirmed.
Minimum: >= 0
Example: 6
listenToFailureStates boolean
Whether or not to listen to failed transactions on chain.
javascript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
var walletId = '58d99…39604';
var url = 'http://your.server.com/webhook';

bitgo
  .coin('tbtc')
  .wallets()
  .get({ id: walletId })
  .then(function (wallet) {
    return wallet.addWebhook({
      url: url,
      type: 'transfer',
    });
  })
  .then(function (webhook) {
    // print the new webhook
    console.dir(webhook);
  });

200 Response

allToken boolean
Example: false
label string
Example: Test Webhook
created string <date-time>
Example: {}
url string <uri>required
Example: https://your.server.com/webhook
version integer
2 for coins running on API v2.
Example: 2
numConfirmations integer
Example: 6
state string
If "active", indicates the webhook can trigger and send to the URL. If "suspended", indicates the webhook can't trigger.
Allowed values: active suspended
Example: active
successiveFailedAttempts integer
Example: 0
walletId string
allowBlockedHosts boolean

400 Response

One of
error string required
Human-readable error message
requestId string required
Client request id
context object
Properties that apply to a specific error name
name string required
Error code