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 state updates).
  3. (Ripple, ETH only) Address confirmation webhooks will fire when an address has been initialized on the wallet.
  4. Wallet-level pending approvals are scoped to a wallet. Possible approvers are determined by the wallet admins. Usually, these involve transaction requests/policy changes.
  5. Enterprise-level pending approvals belong to the enterprise. Possible approvers are determined by the enterprise owners. These usually involve adding/removing users from the enterprise or enterprise-level policy changes. 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
id string
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
label string
Example: Test Webhook
created string <date-time>
Example: {}
coin string
A cryptocurrency or token ticker symbol.
Example: btc
type string
Event type to listen to.
Allowed values: transfer transaction pendingapproval address_confirmation lowFee
Example: transfer
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
lastAttempt string <date-time>
Example: {}
failingSince string <date-time>
Example: {}
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