REST API›Wallet & Transact›Webhook

POST

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.

Path Params

  • coin string required
    A cryptocurrency symbol or token ticker symbol

    at least 1 characters

  • walletId string required

    at least 1 characters · matches ^[0-9a-f]{32}$

Body Params

object

  • type string enum required
    Event type to listen to.
    txRequesttxRequestTransactiontransfertransactiontransactionRemovedtransactionExpirependingapprovalblockadminaddress_confirmationlowFeecircuitBreakerlowFeeAddressBalancetransaction_finality_on_l1stuckTxunspentExpirytwoStepTransfertwoStepDeposittwoStepWithdrawalpendingDecryption
  • url string uri required
    URL to fire the webhook to.

    at least 1 characters

  • 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.
  • allToken boolean
    Triggers on coin transfers and token transfers for ETH and Stellar. Must be set to true to receive webhooks for Trade accounts.

    Defaults to false

  • listenToFailureStates boolean
    Whether or not to listen to failed transactions on chain.
  • txRequestStates array of string enums
    pendingApprovalcanceledrejectedinitializedpendingDeliverydeliveredpendingUserSignaturependingUserCommitmentpendingUserRSharependingUserGSharereadyToSendsignedfailed
  • txRequestTransactionStates array of string enums
    initializedpendingSignatureeddsaPendingCommitmenteddsaPendingRShareeddsaPendingGShareecdsaMPCv2Round1ecdsaMPCv2Round2ecdsaMPCv2Round3eddsaMPCv2Round1eddsaMPCv2Round2eddsaMPCv2Round3readyToCombineSharessignedhelddeliveredinvalidSignaturerejected
  • customHttpHeaders map of strings
    Custom HTTP header key/values to be included with every notification for the webhook.

Responses

200
OK

Response Body

object

Webhook response scoped to wallet webhook types — coin is required.
  • id string required

    matches ^[0-9a-f]{32}$

  • created string date-time required
  • coin string required
    A cryptocurrency or token ticker symbol.
  • url string uri required
  • version number required
    2 for coins running on API v2.
  • scope string enum required
    walletenterpriseorganizationsafe
  • state string enum required
    If 'active', indicates the webhook can trigger and send to the URL. If 'suspended', indicates the webhook can't trigger.
    activesuspended
  • successiveFailedAttempts number required
  • 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

    matches ^[0-9a-f]{32}$

  • userId string
  • type string enum
    Event type to listen to.
    txRequesttxRequestTransactiontransfertransactiontransactionRemovedtransactionExpirependingapprovalblockadminaddress_confirmationlowFeecircuitBreakerlowFeeAddressBalancetransaction_finality_on_l1stuckTxunspentExpirytwoStepTransfertwoStepDeposittwoStepWithdrawalpendingDecryption
  • numConfirmations number
  • lastAttempt string date-time
  • failingSince string date-time
  • allToken boolean
  • txRequestStates array of string enums
    pendingApprovalcanceledrejectedinitializedpendingDeliverydeliveredpendingUserSignaturependingUserCommitmentpendingUserRSharependingUserGSharereadyToSendsignedfailed
  • txRequestTransactionStates array of string enums
    initializedpendingSignatureeddsaPendingCommitmenteddsaPendingRShareeddsaPendingGShareecdsaMPCv2Round1ecdsaMPCv2Round2ecdsaMPCv2Round3eddsaMPCv2Round1eddsaMPCv2Round2eddsaMPCv2Round3readyToCombineSharessignedhelddeliveredinvalidSignaturerejected
400
Bad Request

Response Body

object

  • name string
    Error code
  • context map of objects required
    Properties that apply to a specific error name
    context object
    • <key> object
  • error string required
    Human-readable error message
  • requestId string required
    Client request id
401
Unauthorized

Response Body

object

  • name string
    Error code
  • context map of objects required
    Properties that apply to a specific error name
    context object
    • <key> object
  • error string required
    Human-readable error message
  • requestId string required
    Client request id
403
Forbidden

Response Body

object

  • name string
    Error code
  • context map of objects required
    Properties that apply to a specific error name
    context object
    • <key> object
  • error string required
    Human-readable error message
  • requestId string required
    Client request id
404
Not Found

Response Body

object

  • name string
    Error code
  • context map of objects required
    Properties that apply to a specific error name
    context object
    • <key> object
  • error string required
    Human-readable error message
  • requestId string required
    Client request id
500
Internal Server Error

Response Body

object

  • name string
    Error code
  • context map of objects required
    Properties that apply to a specific error name
    context object
    • <key> object
  • error string required
    Human-readable error message
  • requestId string required
    Client request id