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 symbol or token ticker symbol
    Example: btc
    Min length: >= 1 characters
  • walletIdstringRequired
    Example: 59cd72485007a239fb00282ed480da1f
    Pattern: ^[0-9a-f]{32}$
    Min length: >= 1 characters

Request Body

type string required
Event type to listen to.
Allowed values: txRequest txRequestTransaction transfer transaction transactionRemoved transactionExpire pendingapproval block admin address_confirmation lowFee circuitBreaker transaction_finality_on_l1
url string <uri>required
URL to fire the webhook to.
Min length: >= 1 characters
Example: https://your.server.com/webhook
label string
Label of the new webhook.
numConfirmations number
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.
Example: 6
allToken boolean
Triggers on coin transfers and token transfers for ETH and Stellar. Must be set to true to receive webhooks for Trade accounts.
Default: false
listenToFailureStates boolean
Whether or not to listen to failed transactions on chain.
txRequestStates array[string]
If supplied, only transaction request state changes from the provided list will trigger notifications. If not provided, all transaction request state changes will trigger notifications.
Allowed values: pendingApproval canceled rejected initialized pendingDelivery delivered pendingUserSignature pendingUserCommitment pendingUserRShare pendingUserGShare readyToSend signed failed
txRequestTransactionStates array[string]
If supplied, only transaction request transaction state changes from the provided list will trigger notifications. If not provided, all transaction request transaction state changes will trigger notifications.
Allowed values: initialized pendingSignature eddsaPendingCommitment eddsaPendingRShare eddsaPendingGShare ecdsaMPCv2Round1 ecdsaMPCv2Round2 ecdsaMPCv2Round3 readyToCombineShares signed held delivered invalidSignature rejected
json
1{ 2 "type": "txRequest", 3 "url": "https://your.server.com/webhook", 4 "label": "string", 5 "numConfirmations": 6, 6 "allToken": false, 7 "listenToFailureStates": true, 8 "txRequestStates": [ 9 "pendingApproval" 10 ], 11 "txRequestTransactionStates": [ 12 "initialized" 13 ] 14}

200 Response

id string required
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
created string <date-time>required
Example: 2021-01-01T00:00:00.000Z
coin string required
A cryptocurrency or token ticker symbol.
Example: btc
url string <uri>required
Example: https://your.server.com/webhook
version number required
2 for coins running on API v2.
Example: 2
scope string required
Allowed values: wallet enterprise organization
state string required
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 number required
Example: 0
listenToFailureStates boolean required
Whether or not to listen to failed transactions on chain.
label string
Label of the new webhook.
walletId string
enterpriseId string
organizationId string
Example: 59cd72485007a239fb00282ed480da1f
Match pattern: ^[0-9a-f]{32}$
userId string
type string
Event type to listen to.
Allowed values: txRequest txRequestTransaction transfer transaction transactionRemoved transactionExpire pendingapproval block admin address_confirmation lowFee circuitBreaker wallet_confirmation bankAccount userKycState enterpriseKycState identityStatus accessToken accountCreated contractSigned fundsDeposited kycResult policyBalanceChange transaction_finality_on_l1
numConfirmations number
Example: 6
lastAttempt string <date-time>
Example: 2021-01-01T00:00:00.000Z
failingSince string <date-time>
Example: 2021-01-01T00:00:00.000Z
allToken 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: pendingApproval canceled rejected initialized pendingDelivery delivered pendingUserSignature pendingUserCommitment pendingUserRShare pendingUserGShare readyToSend signed 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 ecdsaMPCv2Round1 ecdsaMPCv2Round2 ecdsaMPCv2Round3 readyToCombineShares signed held delivered invalidSignature rejected
json
1{ 2 "id": "59cd72485007a239fb00282ed480da1f", 3 "created": "2021-01-01T00:00:00.000Z", 4 "coin": "btc", 5 "url": "https://your.server.com/webhook", 6 "version": 2, 7 "scope": "wallet", 8 "state": "active", 9 "successiveFailedAttempts": 0, 10 "listenToFailureStates": true, 11 "label": "string", 12 "walletId": "string", 13 "enterpriseId": "string", 14 "organizationId": "59cd72485007a239fb00282ed480da1f", 15 "userId": "string", 16 "type": "txRequest", 17 "numConfirmations": 6, 18 "lastAttempt": "2021-01-01T00:00:00.000Z", 19 "failingSince": "2021-01-01T00:00:00.000Z", 20 "allToken": true, 21 "txRequestStates": [ 22 "pendingApproval" 23 ], 24 "txRequestTransactionStates": [ 25 "initialized" 26 ] 27}

400 Response

name string
Error code
context object required
Properties that apply to a specific error name
error string required
Human-readable error message
requestId string required
Client request id
json
1{ 2 "name": "string", 3 "context": {}, 4 "error": "string", 5 "requestId": "string" 6}

401 Response

name string
Error code
context object required
Properties that apply to a specific error name
error string required
Human-readable error message
requestId string required
Client request id
json
1{ 2 "name": "string", 3 "context": {}, 4 "error": "string", 5 "requestId": "string" 6}

403 Response

name string
Error code
context object required
Properties that apply to a specific error name
error string required
Human-readable error message
requestId string required
Client request id
json
1{ 2 "name": "string", 3 "context": {}, 4 "error": "string", 5 "requestId": "string" 6}

404 Response

name string
Error code
context object required
Properties that apply to a specific error name
error string required
Human-readable error message
requestId string required
Client request id
json
1{ 2 "name": "string", 3 "context": {}, 4 "error": "string", 5 "requestId": "string" 6}

500 Response

name string
Error code
context object required
Properties that apply to a specific error name
error string required
Human-readable error message
requestId string required
Client request id
json
1{ 2 "name": "string", 3 "context": {}, 4 "error": "string", 5 "requestId": "string" 6}