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