Webhook HTTP API

How to use

Requirements

Webhook methods

WhiteBIT withdraw from main balance

Why Webhooks?

Webhooks deliver real-time HTTP notifications when events occur on a WhiteBIT account — deposits arriving, withdrawals completing, codes being applied, and refunds processing. Without webhooks, the only alternative is polling the deposit/withdrawal history endpoints repeatedly. Webhooks vs polling:

	Webhooks	Polling
Latency	Real-time (seconds)	Depends on polling interval
Server load	Event-driven — no wasted requests	Constant requests, mostly empty
Reliability	A small number of delivery attempts, spaced roughly an hour apart, over about one day (best-effort)	As reliable as the polling loop
Recommended for	Production payment flows	Fallback for outages exceeding the delivery window

There is no webhook replay mechanism. If every delivery attempt fails, the event is dropped. Implement polling of the deposit / withdrawal history endpoint as a fallback so events can be reconciled after extended consumer downtime.

Common use cases:

Payment processing — Detect incoming deposits and credit end users automatically
Withdrawal monitoring — Track withdrawal lifecycle from creation to completion or cancellation
Code redemption — Receive notification when a WhiteBIT Code is applied
Refund handling — Detect successful or failed refunds for reconciliation
Virtual account monitoring — Receive bank details when a virtual account becomes active, without polling the status endpoint

How to use

A webhook is a separate entity with its own generated key and secret. It is not a property of a trading API key, and a trading API key never carries a webhook URL. An account has at most one webhook. The platform enforces this limit, so a second webhook cannot be created on the same account. A sub-account counts as a separate account, so the main account and each sub-account can have one webhook. Each deposit and withdrawal event goes to the webhook of the account that owns the transaction: the main account’s webhook does not receive sub-account events, and the payload carries no sub-account identifier. A sub-account webhook can be created only at whitebit.com, not through the API. To track sub-account deposits from an integration, poll the deposit/withdraw history of each sub-account with the sub-account’s API key. Event types are selected on the webhook itself, so a single URL receives every event type subscribed on it.

Log in to whitebit.com.
Open the API keys tab.
Select the web-hook configuration tab.
Paste the correct URI for the web server to process web-hook calls.
Press Generate a new key button and toggle the activation switcher to “Activated”.

To create a sub-account webhook, log in to the main account at whitebit.com, switch the session to the sub-account, and then follow steps 2 to 5.

The secret key is shown only once. Save it in a secure key store.

Requirements

For web hook keys generation

Before using webhooks, verify ownership of the domain set as the webhook destination. Use one of three methods:

Add a TXT DNS record to the domain with the webhook public key.
Add the plain text file whiteBIT-verification.txt to the root domain folder and provide public web access. Place the public webhook key in the file.
Implement the /whiteBIT-verification endpoint to respond with 200 OK and return a JSON array of public webhook keys. Example: ["<public-webhook-key>"]

Passing one of these checks enables the webhook. Verification runs per webhook key. The /whiteBIT-verification endpoint can return the public keys of several webhooks, such as the main account’s and each sub-account’s, so every key verifies against the same domain without a new DNS record.

For processing web-hook requests

All web hook requests are performing using POST method and with application/json content type. Consumer server should respond with 200 HTTP status code. If the consumer cannot handle the webhook, the platform retries delivery a small number of times spaced roughly an hour apart, over a window of about one day. Treat the exact cadence as best-effort, not a contract, and pair webhook consumption with periodic history polling for reconciliation.

Body data

All web-hook requests are performing with

{
  "method": "string",
  "params": {
    "nonce": 0
  },
  "id": "uniqueID"
}

method - string. The name of method which was evaluated. Webhook methods include the following:

code.apply. Performs when code owned by a customer was applied.
deposit.accepted, deposit.updated, deposit.processed, deposit.canceled. These methods report the stages of a deposit; see WhiteBIT deposit to main balance. Not every stage sends a webhook: a deposit canceled with status 9 sends none, so poll the deposit/withdraw history as well.
deposit.aml_frozen. Sent when a deposit enters status 21; see Deposit and withdrawal status codes.
withdraw.unconfirmed, withdraw.pending, withdraw.canceled, withdraw.successful. These methods report each stage of a withdrawal; see WhiteBIT withdraw from main balance.
refund.successful, refund.failed. These methods report the result of a deposit refund to the webhook of the account that owns the deposit; see WhiteBIT refund successful and WhiteBIT refund failed.

id - string. Uuid to identify every request. params - the request payload. Contains data about the actions triggering the webhook call. The field also contains a nonce. ‘nonce’ - a number always greater than the previous request’s nonce number

Request headers

Also, all request contains additional data in headers:

'Content-type': 'application/json'
'X-TXC-APIKEY': api_key - the WhiteBIT webhook API key
'X-TXC-PAYLOAD': payload' - where payload is base64-encoded body data
'X-TXC-SIGNATURE': signature - where signature is hex(HMAC_SHA512(payload), key=api_secret)). api_secret is the secret of the generated webhook key.

On the consumer side, process the security headers to verify the request originated from WhiteBIT.

Source IP range

WhiteBIT delivers webhooks from a fixed IP range. The account manager provides the range for allowlisting; the portal does not publish it. Verify the origin of each request with the request headers.

WebHook Methods

WhiteBIT code apply

Performed when code was applied. Request example:

{
  "method": "code.apply",
  "params": {
    "code": "<SOME_WHITE_BIT_CODE>",
    "nonce": 1
  },
  "id": "45a1d85d-2fdf-483e-8dfa-6d253148c730"
}

WhiteBIT deposit to main balance

Performed when a deposit is accepted. Every fiat deposit sends deposit.accepted; a crypto deposit does not always send deposit.accepted, so do not wait for the event before handling deposit.updated or deposit.processed. Request example:

{
  "method": "deposit.accepted",
  "params": {
    "address": "wallet address", // deposit address
    "amount": "0.000600000000000000", // amount of deposit
    "createdAt": 1593437922, // timestamp of deposit
    "currency": "Tether US", // deposit currency
    "description": "", // deposit description
    "fee": "0.000000000000000000", // deposit fee
    "memo": "", // deposit memo
    "method": 1, // called method 1 - deposit, 2 - withdraw
    "network": "ERC20", // if currency is multi network
    "status": 15, // transaction status
    "ticker": "USDT_ETH", // deposit currency ticker
    "transactionHash": "transaction hash", // deposit transaction hash
    "uniqueId": null, // unique Id of deposit
    "confirmations": {
      // if transaction has confirmations info it will display here
      "actual": 1, // current block confirmations
      "required": 2 // required block confirmation for successful deposit
    }
  },
  "id": "uuid"
}

Performed when a crypto deposit changes (fiat deposits do not send deposit.updated): a new confirmation count, a deposit recorded as uncredited (status 22), or an early credit (status 29) where the network’s confirmations_for_trading is lower than confirmations. Request example:

{
  "method": "deposit.updated",
  "params": {
    "address": "wallet address", // deposit address
    "amount": "0.000600000000000000", // amount of deposit
    "createdAt": 1593437922, // timestamp of deposit
    "currency": "Tether US", // deposit currency
    "description": "update", // deposit description
    "fee": "0.000000000000000000", // deposit fee
    "memo": "", // deposit memo
    "network": "ERC20", // if currency is multi network
    "status": 15, // transaction status
    "ticker": "USDT_ETH", // deposit currency ticker
    "transactionHash": "transaction hash", // deposit transaction hash
    "uniqueId": null, // unique Id of deposit
    "confirmations": {
      // if transaction has confirmations info it will display here
      "actual": 1, // current block confirmations
      "required": 2 // required block confirmation for successful deposit
    }
  },
  "id": "uuid"
}

Performed when the deposit is processed and available on the balance (status 3 or 7). For a crypto deposit this happens when the network fully confirms it; any hold from an early credit (status 29) clears. Request example:

{
  "method": "deposit.processed",
  "params": {
    "address": "wallet address", // deposit address
    "amount": "0.000600000000000000", // amount of deposit
    "createdAt": 1593437922, // timestamp of deposit
    "currency": "Tether US", // deposit currency
    "description": "", // deposit description
    "fee": "0.000000000000000000", // deposit fee
    "memo": "", // deposit memo
    "method": 1, // called method 1 - deposit, 2 - withdraw
    "network": "ERC20", // if currency is multi network
    "status": 3, // transaction status, 3 or 7 - successful
    "ticker": "USDT_ETH", // deposit currency ticker
    "transactionHash": "transaction hash", // deposit transaction hash
    "uniqueId": null, // unique Id of deposit
    "confirmations": {
      // if transaction has confirmations info it will display here
      "actual": 2, // current block confirmations
      "required": 2 // required block confirmation for successful deposit
    }
  },
  "id": "uuid"
}

Performed when a deposit is canceled with status 4. A deposit canceled with status 9 sends no webhook; the deposit appears only in the deposit/withdraw history. Request example:

{
  "method": "deposit.canceled",
  "params": {
    "address": "wallet address", // deposit address
    "amount": "100.00", // amount of deposit
    "createdAt": 1593437922, // timestamp of deposit
    "currency": "Tether US", // deposit currency
    "description": "", // deposit description
    "fee": "0.000000000000000000", // deposit fee
    "memo": "", // deposit memo
    "method": 1, // called method 1 - deposit, 2 - withdraw
    "network": "ERC20", // if currency is multi network, "null" if no multi network
    "status": 4, // transaction status, 4 - canceled
    "ticker": "USDT_ETH", // deposit currency ticker
    "transactionHash": "transaction hash", // deposit transaction hash
    "uniqueId": "54bffeb7-7a8f-43f8-bcd8-f14ec10fee85", // transaction UUID of the deposit
    "confirmations": {
      // if transaction has confirmations info it will display here
      "actual": 1, // current block confirmations
      "required": 32 // required block confirmation for successful deposit
    }
  },
  "id": "uuid"
}

Travel Rule deposit statuses (EEA)

For EEA users, an inbound deposit may be frozen pending Travel Rule verification, and the deposit carries a Travel Rule status code (see Deposit and withdrawal status codes). There is currently no webhook for these transitions, so track status changes via the deposit/withdraw history. When the Travel Rule API is enabled for the account, submit the deposit originator data via Submit deposit originator data (POST /api/v4/travel-rule/deposit/verification); otherwise the deposit is verified manually at whitebit.com. Funds are credited only after successful verification. For details on Travel Rule requirements and the travelRule object for withdrawals, see Regulatory Compliance.

Deposit and withdrawal status codes

Status codes that the deposit/withdraw history returns include the following. Deposit status codes:

Code	Status	Description
3, 7	Successful	Deposit successful; final state
4	Canceled	Deposit canceled; final state. Cannot be refunded through the API
9	Canceled	Deposit canceled; final state. No webhook is sent; read the status from the history. Only a deposit that was frozen (status 21, 27 or 28) before it was canceled can be refunded through the API; see Refund deposit
15	Pending	Deposit detected, awaiting confirmations
21	On hold	Deposit held for review; not final
22	Uncredited	Detected, not credited yet; not final. A deposit below the network minimum waits in this status: deposits to the same address add up and are credited together once the total reaches the minimum; otherwise the deposit is canceled with status 9 after 7 days
23	Pending	Deposit in progress; not final
27	Travel Rule frozen	Deposit frozen; the account holder must complete Travel Rule verification (EEA)
28	Travel Rule processing	Travel Rule data submitted, verification in progress (EEA)
29	Credited, on hold	Funds credited; part may stay held until the network fully confirms the deposit; not final

Withdrawal status codes:

Code	Status	Description
1, 2, 6, 10–17	Pending	Withdrawal in progress
3, 7	Successful	Withdrawal completed, funds sent
4	Canceled	Withdrawal canceled; final state; the amount returns to the balance
5	Unconfirmed	Withdrawal created; reported with `withdraw.unconfirmed`; not final
18	Partially successful	Part of the withdrawal succeeded (fiat with `partialEnable: true`)
21	AML frozen	Withdrawal frozen by AML controls

WhiteBIT virtual account status

Performed when the status of a virtual account changes. The deposit.virtual_account_status event removes the need to poll Get virtual account status for status changes; polling remains available. The event covers virtual accounts of every provider, including accounts registered through the WhiteBIT interface. To receive the event, enable the virtual account status event in the deposit group of the webhook configuration. On a webhook created before the event was introduced, the event is disabled by default and existing event subscriptions do not change. A webhook activated for the first time subscribes to every event, including deposit.virtual_account_status. The platform sends the event on every status change of the virtual account:

Activation — the provider allocates the account, and status becomes active.
Rejection — the provider refuses to open the account, and status becomes rejected.
Closure — the provider closes the account, and status becomes closed. A closure attempt that leaves the account open does not trigger the event.

Registration does not trigger the event: the initial pending status that Create virtual account returns is not a status change. Deposits to the virtual account do not trigger the event either; deposit status changes arrive as the deposit.* events above. The platform sends the event only after Get virtual account status returns the new status, so both sources report the same status for the same account. Request example:

{
  "method": "deposit.virtual_account_status",
  "params": {
    "provider": "SEPA_BCB_GROUP",
    "status": "active",
    "paymentDetails": {
      "beneficiary": "Acme Trading Ltd",
      "iban": "DE89370400440532013000",
      "bic": "COBADEFFXXX"
    },
    "timestamp": 1761566400,
    "nonce": 1
  },
  "id": "uuid"
}

Field	Type	Description
`provider`	String	Fiat provider of the virtual account, for example `SEPA_BCB_GROUP`.
`status`	String	New status of the virtual account. Uses the same values as `status` in Get virtual account status.
`paymentDetails`	Object	Bank details for incoming bank transfers, with the same fields as `paymentDetails` in Get virtual account status. Contains data only when `status` is `active`. For other statuses, the field is an empty object `{}`.
`timestamp`	Integer	Time the platform registered the status change, as a Unix timestamp in seconds. Retries carry the original value. Compare `timestamp` with the last processed value to discard a notification that arrives out of order.
`nonce`	Integer	Request nonce, common to every webhook request.

The event carries the bank details that end users send deposits to. Verify the X-TXC-SIGNATURE header as described in Request headers before using paymentDetails.

Delivery follows the retry policy in Processing webhook requests. A failed delivery does not change the virtual account status. After the last retry fails, the platform drops the notification; use Get virtual account status to read the current status and bank details.

WhiteBIT withdraw from main balance

Performed when withdraw was created (status 5). A sub-account withdrawal that waits for main-account confirmation sends no webhook while it waits; after the main account confirms it, withdraw.unconfirmed is sent to the webhook of the sub-account that owns the withdrawal. Request example:

{
  "method": "withdraw.unconfirmed",
  "params": {
    "address": "wallet address", // withdraw address
    "amount": "100.00", // amount of withdraw
    "createdAt": 1593437922, // timestamp of withdraw
    "currency": "Tether US", // withdraw currency
    "ticker": "USDT", // withdraw currency ticker
    "description": null, // withdraw description
    "fee": "0.000000000000000000", // withdraw fee
    "memo": "", // withdraw memo
    "method": 2, // called method 1 - deposit, 2 - withdraw
    "network": "TRC20", // if currency is multi network, "null" if no multi network
    "status": 5, // transaction status
    "transactionHash": "transaction hash", // withdraw transaction hash
    "uniqueId": null // unique Id of withdraw
  },
  "id": "uuid"
}

Performed when withdraw is pending. Request example:

{
  "method": "withdraw.pending",
  "params": {
    "address": "wallet address", // withdraw address
    "amount": "100.00", // amount of withdraw
    "createdAt": 1593437922, // timestamp of withdraw
    "currency": "Tether US", // withdraw currency
    "ticker": "USDT", // withdraw currency ticker
    "description": null, // withdraw description
    "fee": "0.000000000000000000", // withdraw fee
    "memo": "", // withdraw memo
    "method": 2, // called method 1 - deposit, 2 - withdraw
    "network": "TRC20", // if currency is multi network, "null" if no multi network
    "status": 15, // transaction status
    "transactionHash": "transaction hash", // withdraw transaction hash
    "uniqueId": null // unique Id of withdraw
  },
  "id": "uuid"
}

Performed when a withdrawal is canceled, including a withdrawal that fails processing after a retry when two withdrawals compete for the same balance. Request example:

{
  "method": "withdraw.canceled",
  "params": {
    "address": "wallet address", // withdraw address
    "amount": "100.00", // amount of withdraw
    "createdAt": 1593437922, // timestamp of withdraw
    "currency": "Tether US", // withdraw currency
    "ticker": "USDT", // withdraw currency ticker
    "description": null, // withdraw description
    "fee": "0.000000000000000000", // withdraw fee
    "memo": "", // withdraw memo
    "method": 2, // called method 1 - deposit, 2 - withdraw
    "network": "TRC20", // if currency is multi network, "null" if no multi network
    "status": 4, // transaction status, 4 - canceled
    "transactionHash": "transaction hash", // withdraw transaction hash
    "uniqueId": null // unique Id of withdraw
  },
  "id": "uuid"
}

Performed when withdraw was completed. Request example:

{
  "method": "withdraw.successful",
  "params": {
    "address": "wallet address", // withdraw address
    "amount": "100.00", // amount of withdraw
    "createdAt": 1593437922, // timestamp of withdraw
    "currency": "Tether US", // withdraw currency
    "ticker": "USDT", // withdraw currency ticker
    "description": null, // withdraw description
    "fee": "0.000000000000000000", // withdraw fee
    "memo": "", // withdraw memo
    "method": 2, // called method 1 - deposit, 2 - withdraw
    "network": "TRC20", // if currency is multi network, "null" if no multi network
    "status": 3, // transaction status, 3 or 7 - successful
    "transactionHash": "transaction hash", // withdraw transaction hash
    "uniqueId": null // unique Id of withdraw
  },
  "id": "uuid"
}

WhiteBIT refund successful

Triggered after the system successfully completes a refund. In this webhook, refundAmount is the amount sent on-chain and refundNetworkFee is the network fee. Refund history returns neither value: its refundAmount is the deposit amount. memo is the destination memo sent in the refund request. Unlike deposit and withdraw webhooks, which send "", refund webhooks send null when no memo was provided. Request example:

{
  "method": "refund.successful",
  "params": {
    "transactionId": "5e112b38-...",
    "status": "completed",
    "refundAddress": "GDTSOI56...",
    "depositAmount": "100",
    "currency": "Tether USDT",
    "ticker": "USDT",
    "network": "ERC-20",
    "createdAt": 1733924412,
    "processedAt": 1733925012,
    "refundNetworkFee": "1",
    "refundAmount": "99",
    "refundHash": "0x767ebd2...",
    "memo": null, // refund destination memo, null if not provided
    "nonce": 0
  },
  "id": "uuid"
}

WhiteBIT refund failed

Triggered when a refund fails: the review rejects the refund, or a refund attempt fails. After a rejection, Get refund history shows the refund as canceled, which is final, and no funds are sent. Request example:

{
  "method": "refund.failed",
  "params": {
    "transactionId": "5e112b38-...",
    "status": "failed",
    "refundAddress": "GDTSOI56...",
    "depositAmount": "100",
    "currency": "Tether USDT",
    "ticker": "USDT",
    "network": "ERC-20",
    "createdAt": 1733924412,
    "processedAt": 1733925012,
    "memo": null, // refund destination memo, null if not provided
    "nonce": 0
  },
  "id": "uuid"
}

When a refund attempt fails for an internal reason, Get refund history still shows the refund as in_process and the refund is not final. A refund with status canceled in the refund history is final.

What’s Next

Payment Integration

End-to-end guide for deposit and withdrawal processing with webhook reconciliation.

Security Best Practices

HMAC-SHA512 signature verification, API key management, and production hardening.

Get started

Partner Solutions

Recipes

Products

Platform Features

Core Concepts

Best Practices

AI Hub

Resources

How to use

Requirements

Webhook methods

WhiteBIT withdraw from main balance

Why Webhooks?

How to use

Requirements

For web hook keys generation

For processing web-hook requests

Body data

Request headers

Source IP range

WebHook Methods

WhiteBIT code apply

WhiteBIT deposit to main balance

Travel Rule deposit statuses (EEA)

Deposit and withdrawal status codes

WhiteBIT virtual account status

WhiteBIT withdraw from main balance

WhiteBIT refund successful

WhiteBIT refund failed

What’s Next

Payment Integration

Security Best Practices