Sign in
latestOpenAPI 3.0.32026-08-224982,0272.8 MB

e445c15e5bee

Webhook

Add wallet webhook

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. Learn more about webhooks on the Developer Portal.

Note: Before you process webhook notifications, BitGo strongly recommends that you verify response details by fetching the transfer or block data from BitGo. For example, if you create a transfer webhook and you receive a transfer ID, pass that ID to the Get Transfer endpoint to verify the transfer details.

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

Path parameters

coinstring required

A cryptocurrency symbol or token ticker symbol

Example:btc
walletIdstring required
Example:59cd72485007a239fb00282ed480da1f

Request body

type'txRequest' | 'txRequestTransaction' | 'transfer' | 'transaction' | 'transactionRemoved' | 'transactionExpire' | 'pendingapproval' | 'block' | 'admin' | 'address_confirmation' | 'lowFee' | 'circuitBreaker' | 'lowFeeAddressBalance' | 'transaction_finality_on_l1' | 'stuckTx' | 'unspentExpiry' | 'twoStepTransfer' | 'twoStepDeposit' | 'twoStepWithdrawal' | 'endInvestorOnboardingInvite' | 'endInvestorOnboardingAccepted' | 'pendingDecryption' required
urlstring uri required

URL to fire the webhook to.

labelstring

Label of the new webhook.

numConfirmationsnumber

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.

allTokenboolean

Triggers on coin transfers and token transfers for ETH and Stellar. Must be set to true to receive webhooks for Trade accounts.

listenToFailureStatesboolean

Whether or not to listen to failed transactions on chain.

txRequestStatesstring[]
txRequestTransactionStatesstring[]
customHttpHeadersobject

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

Example request

{
  "url": "https://your.server.com/webhook",
  "numConfirmations": 6
}

Response

OK

idstring required
createdstring date-time required
coinstring required

A cryptocurrency or token ticker symbol.

urlstring uri required
versionnumber required

2 for coins running on API v2.

scope'wallet' | 'enterprise' | 'organization' | 'safe' required
state'active' | 'suspended' required

If 'active', indicates the webhook can trigger and send to the URL. If 'suspended', indicates the webhook can't trigger.

successiveFailedAttemptsnumber required
listenToFailureStatesboolean required

Whether or not to listen to failed transactions on chain.

labelstring

Label of the new webhook.

walletIdstring
enterpriseIdstring
organizationIdstring
userIdstring
type'txRequest' | 'txRequestTransaction' | 'transfer' | 'transaction' | 'transactionRemoved' | 'transactionExpire' | 'pendingapproval' | 'block' | 'admin' | 'address_confirmation' | 'lowFee' | 'circuitBreaker' | 'lowFeeAddressBalance' | 'transaction_finality_on_l1' | 'stuckTx' | 'unspentExpiry' | 'twoStepTransfer' | 'twoStepDeposit' | 'twoStepWithdrawal' | 'endInvestorOnboardingInvite' | 'endInvestorOnboardingAccepted' | 'pendingDecryption'
numConfirmationsnumber
lastAttemptstring date-time
failingSincestring date-time
allTokenboolean
txRequestStatesstring[]
txRequestTransactionStatesstring[]

Example response

{
  "id": "59cd72485007a239fb00282ed480da1f",
  "created": "2021-01-01T00:00:00.000Z",
  "coin": "btc",
  "url": "https://your.server.com/webhook",
  "version": 2,
  "state": "active",
  "organizationId": "59cd72485007a239fb00282ed480da1f",
  "numConfirmations": 6,
  "lastAttempt": "2021-01-01T00:00:00.000Z",
  "failingSince": "2021-01-01T00:00:00.000Z"
}