Trade Webhooks
Stay in sync with the status of all executed trades.
Bitnob emits webhook events when a trade completes or fails. These events allow your system to respond to state changes in real time — updating user balances, marking orders as settled, or triggering downstream workflows.
Events
| Event Type | Description |
|---|---|
| trade.completed | A USDT ↔ BTC trade has been executed and settled successfully. |
| trade.failed | A trade request failed due to quote expiry, insufficient balance, or system error. |
Webhook: trade.completed
Sample Payload
trade.completed Payload
Payload Fields
| Field | Description |
|---|---|
| event | Always trade.completed |
| tradeId | Unique ID of the executed trade. |
| reference | Your internal reference ID for the trade. |
| from | Source asset (usdt or bitcoin). |
| to | Destination asset. |
| inputAmount | Amount that was converted (in cents or sats). |
| outputAmount | Amount received (in sats or cents). |
| rate | Executed exchange rate. |
| walletId | Bitnob wallet that received the output. |
| status | Always completed. |
| timestamp | ISO 8601 timestamp when the trade completed. |
Webhook: trade.failed
Sample Payload
trade.failed Payload
Payload Fields
| Field | Description |
|---|---|
| event | Always trade.failed. |
| reference | Your original reference ID. |
| from | Source asset of attempted trade. |
| to | Target asset. |
| inputAmount | Requested trade amount. |
| reason | Reason for failure (e.g., Quote expired, Insufficient balance). |
| status | Always failed. |
| timestamp | Time of failure in ISO format. |
Security & Verification
All webhook events:
Are delivered via HTTPS POST requests
Include an X-Bitnob-Signature header (HMAC SHA-256)
Can be verified using your webhook secret (see Tooling > HMAC Generator)
Best Practices
Match reference in the payload with your internal ledger or transaction object
Log all webhook events in a dedicated table or log stream
Make webhook handlers idempotent — you may receive duplicates
Use status, timestamp, and rate to reconcile trade outcomes precisely
Alert internally on trade.failed events above a certain volume threshold
