---
title: "Add wallet webhook"
method: POST
path: "/api/v2/{coin}/wallet/{walletId}/webhooks"
tags: ["Webhook"]
---

# 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`. Learn more about webhooks on the
[Developer Portal](/docs/webhooks-overview#/).

**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](/reference/v2walletgettransfer#/) endpoint to verify the transfer
details.

## Path parameters

- `coin` string, required — A cryptocurrency symbol or token ticker symbol
- `walletId` string, required

## Request body

- object
  - `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
  - `url` string, uri, required — URL to fire the webhook to.
  - `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.
  - `listenToFailureStates` boolean — Whether or not to listen to failed transactions on chain.
  - `txRequestStates` string[]
  - `txRequestTransactionStates` string[]
  - `customHttpHeaders` object — Custom HTTP header key/values to be included with every notification for the webhook.

## Response `200`

OK

- WalletWebhookResponse — Webhook response scoped to wallet webhook types — `coin` is required.
  - `id` string, required
  - `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` '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.
  - `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
  - `userId` string
  - `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'
  - `numConfirmations` number
  - `lastAttempt` string, date-time
  - `failingSince` string, date-time
  - `allToken` boolean
  - `txRequestStates` string[]
  - `txRequestTransactionStates` string[]

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `500` — Internal Server Error

---

[API](https://skmtc.net/bitgo/apis/bitgo-api.md) · [All operations](https://skmtc.net/bitgo/apis/bitgo-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bitgo/bitgo-api/revisions/e445c15e5bee/schema)