Webhook HTTP API

Configure webhook callbacks to receive real-time notifications for deposits and withdrawals on WhiteBIT.

How to use

Requirements

Webhook methods

WhiteBIT withdraw from main balance

How to use

1. Log in to whitebit.com.
2. Open the API keys tab.
3. Select the web-hook configuration tab for the API keys.
4. Paste the correct URI for the web server to process web-hook calls.
5. 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:

1. Add a TXT DNS record to the domain with the webhook public key.
2. 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.
3. 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 consumer was unable to handle web-hook, the request will be retry every 10 minutes but not more than 5 times.

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:

1. 'Content-type': 'application/json'
2. 'X-TXC-APIKEY': api_key - the WhiteBIT webhook API key
3. 'X-TXC-PAYLOAD': payload' - where payload is base64-encoded body data
4. '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"
}

Deposit status codes:

• Pending - 15

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"
}