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 supported-pair trade (USDT, USDC, BTC, or NGN) 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
event_id	Unique ID for this event. Use it to de-duplicate deliveries.
tradeId	Unique ID of the executed trade.
reference	Your internal reference ID for the trade.
from	Source asset (usdt, usdc, btc, or ngn).
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.
event_id	Unique ID for this event. Use it to de-duplicate deliveries.
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: an HMAC SHA-512 of the raw request body, keyed with your webhook secret

Must be verified before you parse the body, comparing signatures in constant time — see Verifying Events

Come from the addresses listed under Source IPs

Delivery, Retries and Ordering

Return a 200 as soon as the signature checks out and process afterwards. Slow handlers time out and count as failed

A 2xx response marks the event as delivered. A 400, 404, 410, 422 or 451 response is final and is not retried. Anything else, including a timeout, is retried with increasing delays, up to the retry count set on your webhook (1 to 5 delivery attempts in total). After that, delivery stops

The same event can arrive more than once. De-duplicate on event_id

Events can arrive in any order — a retried delivery may land after a later one. Each trade ends in exactly one terminal event, trade.completed or trade.failed

Retries are finite, so an endpoint that is down long enough misses events permanently. Reconcile with Get Order By ID for anything you still hold as pending

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, so de-duplicate on event_id

Use status, timestamp, and rate to reconcile trade outcomes precisely

Alert internally on trade.failed events above a certain volume threshold