Webhook HTTP API - WhiteBIT

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	~3 delivery attempts spaced roughly hourly over a ~1-day window	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

How to use

Log in to whitebit.com.
Open the API keys tab.
Select the web-hook configuration tab for the API keys.
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”.

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 containing the public webhook key. Example: ["<public-webhook-key>"]

Passing one of these checks enables the webhook.

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. Web hooks API supports such web-hook methods:

code.apply. Performs when code owned by a customer was applied.

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))

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

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 deposit was accepted. 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, // transactions 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 deposit was update. 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, // transactions 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 was processed and is available on the balance. 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": 15, // transactions 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 deposit was canceled. 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": 15, // transactions 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": 32 // required block confirmation for successful deposit
    }
  },
  "id": "uuid"
}

Travel Rule deposit events (EEA)

For EEA users, deposits may be frozen pending Travel Rule verification. When a deposit is frozen, the webhook delivers deposit.updated events with Travel Rule-specific status codes. The end user must complete Travel Rule verification through the WhiteBIT platform UI — the partner cannot submit Travel Rule data via API. For details on Travel Rule requirements and the travelRule object for withdrawals, see Regulatory Compliance. Deposit status codes:

Code	Status	Description
15	Pending	Deposit detected, awaiting confirmations
27	Travel Rule Frozen	Deposit frozen — Travel Rule verification required (EEA)
28	Travel Rule Frozen Processing	Travel Rule verification in progress (EEA)

WhiteBIT withdraw from main balance

Performed when withdraw was created. 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": 15, // transactions 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, // transactions status
    "transactionHash": "transaction hash", // withdraw transaction hash
    "uniqueId": null // unique Id of withdraw
  },
  "id": "uuid"
}

Performed when withdraw was canceled. 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": 15, // transactions status
    "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": 15, // transactions status
    "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. 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...",
    "nonce": 0
  },
  "id": "uuid"
}

WhiteBIT refund failed

Triggered after the system fails to complete a refund. The system rejects the refund if the destination address does not support the required network or asset, or if validation fails. Use a different address or contact support. 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,
    "nonce": 0
  },
  "id": "uuid"
}

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.

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

​WebHook Methods

​WhiteBIT code apply

​WhiteBIT deposit to main balance

​Travel Rule deposit events (EEA)

​WhiteBIT withdraw from main balance

​WhiteBIT refund successful

​WhiteBIT refund failed

​What’s Next

Payment Integration

Security Best Practices

Why Webhooks?

How to use

Requirements

For web hook keys generation

For processing web-hook requests

Body data

Request headers

WebHook Methods

WhiteBIT code apply

WhiteBIT deposit to main balance

Travel Rule deposit events (EEA)

WhiteBIT withdraw from main balance

WhiteBIT refund successful

WhiteBIT refund failed

What’s Next