Add internal wallet webhook

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

Add a webhook to a wallet that sends an HTTP callback from BitGo to a specified URL when specific conditions occur. There is no limit to the amount of internal webhooks a wallet can have.

Wallet-webhook types:

Address confirmation - An address initializes on chain (ETH and XRP only).
Pending approval - A wallet-level policy-triggering event occurs (such as a withdrawal, user change, policy change, pending approval state updates, and so forth).
Transaction request - A transaction request state changes.
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.

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

customHttpHeaders dictionary<string, string>

Custom HTTP header key/values to be included with every notification for the webhook.

string

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 lowFeeAddressBalance wallet_confirmation bankAccount userKycState enterpriseKycState identityStatus accessToken accountCreated contractSigned fundsDeposited kycResult policyBalanceChange reversal transaction_finality_on_l1 stuckTx tradeOrder unspentExpiry twoStepTransfer

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.

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.

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

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

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

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

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

Is this page helpful?