Ctrl+K

Add wallet webhook

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

Add a webhook to a wallet that sends an HTTP callback from BitGo to a specified URL when specific conditions occur. A wallet can have up to 10 webhooks of each wallet-webhook type. Wallet-webhook types:

  1. Address confirmation - An address initializes on chain (ETH and XRP only).
  2. Pending approval - A wallet-level policy-triggering event occurs (such as a withdrawal, user change, policy change, pending approval state updates, and so forth).
  3. Transaction request - A transaction request state changes.
  4. Transfer - Any transfer occurs.

Note: Unconfirmed webhook notifications don't trigger for RBF transactions, or if a transaction confirms on chain immediately after it's sent. BitGo doesn't send '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

One of
type string required
Event type to listen to.
Allowed values: txRequest txRequestTransaction 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: txRequest txRequestTransaction 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
txRequestStates array[string]
If present, only transaction request state changes from the list will trigger notifications. If not present, all transaction request state changes will trigger notifications.
Allowed values: initialized pendingApproval pendingUserCommitment pendingUserRShare pendingUserGShare readyToSend pendingUserSignature pendingDelivery signed delivered canceled rejected failed
txRequestTransactionStates array[string]
If present, only transaction request transaction state changes from the list will trigger notifications. If not present, all transaction request transaction state changes will trigger notifications.
Allowed values: initialized pendingSignature eddsaPendingCommitment eddsaPendingRShare eddsaPendingGShare readyToCombineShares signed held delivered invalidSignature rejected

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