Webhook

Whenever a key event (currently only "order status change") occurs, Binance Connect will send a webhook message, and the partner (client) can receive this message at the webhook callback url and react accordingly, such as updating order data and frontend UI.

Request Headers

Field	Type	Remarks
X-BN-Connect-Timestamp	timestamp	timestamp
X-BN-Connect-Signature	string	SHA256withRSA(requestBody + X-Connect-Timestamp)
X-BN-Connect-For	string	Same with your client id (X-Tesla-ClientId)

Request Body

Field	Type	Remarks
externalOrderId	string	The unique order id from the partner side.
type	int	1: buy, 2: sell, 3: send
status	int	Please refer to "Order status"
payMethodCode	string	The payment method code is from payment method list API
payMethodSubCode	string	The payment method sub code is from payment method list API
fiatCurrency	string	fiat currency
cryptoCurrency	string	crypto currency
fiatAmount	string	fiat amount
cryptoAmount	string	crypto amount
feeAmount	string	fee amount
feeCurrency	string	fee currency, USD or crypto
revenueAmount	string	partner revenue amount
revenueCurrency	string	partner revenue currency, USD or crypto
networkFee	string	network fee amount
withdrawWalletAddress	string	withdraw wallet address
withdrawNetwork	string	withdraw network
withdrawMemo	string	withdraw network memo
withdrawTxHash	string	withdraw tx hash
orderDetailLink	string	order detail link
orderTime	timestamp	order time
completionTime	timestamp	completion time
updateTime	timestamp	update time

Response Body

HTTP status code is 200
Response body is in JSON format.

Field	Type	Remarks
returnCode	string	SUCCESS or other code you wish to return to Binance Connect
returnMessage	string	the message you wish to return to Binance Connect

How signature works

The encryption/decryption and verification process of webhook is exactly the opposite/mirrored of API request process. The sender and receiver of the two are opposite, but they are both processes that signed by the sender with a private key and verified by the receiver with a public key.

For API requests, the partner (client) generates a pair of keys. The private key is kept securely and privately by the partner (client). Then the partner (client) uses the private key to sign when initiating API requests. The public key is shared to Bianance Connect, with which Binance will verify the signature of the API request to ensure that the request is indeed initiated by the partner (client).

For webhook, it's an opposite/mirrored process. Binance Connect generates a pair of keys. The private key is kept securely and privately by Binance Connect. Then Binance Connect uses the private key to sign when initiating the webhook message. The public key is shared to the partner (client), with which the partner (client) can verify the signature of the webhook message to ensure that the message is indeed initiated by Binance.

The webhook signature flow is as follows:

Verify signature

As mentioned above, Binance Connect initiates a webhook request to the webhook callback url provided by the partner (client). And the partner (client) should verify the identity of the request initiator based on the public key provided by Binance Connect.

The example code below shows how to verify signature with public key:

public static boolean verify(String srcData, PublicKey publicKey, String sign) throws Exception {
    Signature signature = Signature.getInstance("SHA256withRSA");
    signature.initVerify(publicKey);
    signature.update(srcData.getBytes());
    return signature.verify(Base64.decodeBase64(sign.getBytes()));
}

Example

Request Body:

{
   "externalOrderId": "180401941923045",
   "type": 1,
   "status": 2,
   "payMethodCode": "BUY_P2P",
   "payMethodSubCode": "BANK",
   "fiatCurrency": "EUR",
   "cryptoCurrency": "USDT",
   "fiatAmount": "100",
   "cryptoAmount": "107.8",
   "feeAmount": "1",
   "feeCurrency": "USDT",
   "revenueAmount": "0.08",
   "revenueCurrency": "USDT",
   "networkFee": "0.5",
   "withdrawWalletAddress": "0xbb4CdB98Bd36B01bD1cBaEA52De08d9173bc095c",
   "withdrawNetwork": "BSC",
   "withdrawMemo": "",
   "withdrawTxHash": "0xcb163e2e6322cd6aa7bc4d45306029e846c0c06e9cdee45a06e88801d1231e71",
   "orderDetailLink": "https://www.binance.com/en/my/wallet/exchange/buysell-history?type=buy",
   "orderTime": 1723186761000,
   "completionTime": 1723206761000,
   "updateTime": 1734446642930
}

Webhook

Request Headers​

Request Body​

Response Body​

How signature works​

The webhook signature flow is as follows:​

Verify signature​

Example​