Observability, Logging, and Traceability
Once your integration is live and moving real money, knowing what happened, when, and why becomes just as important as getting the feature to work in the first place.
This guide covers how to build logging, tracing, and debugging systems around your Bitnob integration — so you can confidently answer questions like:
Did the webhook fire?
Was this swap confirmed?
What rate did the user see?
Why did this payout fail?
Was this user already refunded?
What You Should Be Observing
At a minimum, you should track:
Every request you send to Bitnob
Every webhook you receive
Every reference or quote created
Every error encountered
Every transaction lifecycle: start → success or fail Handle all messaging via webhooks
Logging Principles
Log every transaction by reference
Your log or DB record should include:
Never log full API keys or Authorization headers : Redact sensitive fields before saving logs or printing to terminal.
Include timestamps everywhere : Time-based filtering is critical for debugging delayed payments, race conditions, or webhook mismatches.
Recommended Schema for Transaction Logging
Every time you create a quote, store it alongside your transaction or UI session.
| reference | type | status | quoteId | fromAsset |
|---|---|---|---|---|
tx_123abc | abc | processed | QI_123abc | USDT |
This makes auditing, debugging, and duplicate suppression easy.
Store Quotes with Transaction State
Every time you create a quote, store it alongside your transaction or UI session.
| reference | type | status | quoteId | fromAsset | Webhook Received | createdAt |
|---|---|---|---|---|---|---|
tx_123abc | payout | initiated | QI_123abc | USDT | true | 2025-04-08T12:45:00Z |
tx_123abpo | airtime | delivered | QI_123abc | USDT | true | 2025-04-08T12:45:00Z |
Use this as your internal trace log. Append rather than overwrite fields.
Trace Every Step in the Transaction Flow
Here’s what a full trace should capture:
Your logs should capture each arrow in this diagram. It creates a full timeline of the user experience and system behavior.
Webhook Event Logging
For every webhook:
Store event name, reference, and full payload
Mark whether it was successfully processed
Include delivery attempt count if possible
Log if processing failed due to validation, DB error, or timeout
Real-Time Monitoring
Use tools like:
Datadog, Prometheus, or Grafana for metrics
Logtail, LogDNA, or CloudWatch for logs
Postgres or Redis dashboards for transaction views
Alerting tools for webhook failures or payout spikes
Basic alerts to configure:
Webhook retries exceed 3x
Quote expiry before user pays
Anyone taking their Bitnob integration to production
Payout failure rate > 1% in 5 minutes
Unknown errors in POST /payouts/initiate
Building an Internal Reconciliation Dashboard
As you scale, build a basic tool that lets you:
Search transactions by reference
See raw API request and response
View status history (created, sent, confirmed, failed)
Manually mark transactions as resolved or refunded
Replay failed webhooks
Exposing Traces to Your Users
If your users initiate payments or swaps, expose a limited version of your trace logs to them:
Status: pending, confirmed, expired, failed
Amount: what they sent
Rate: what they got
Timestamps
Next steps if stuck
Observability is what separates test code from a reliable product. It gives you the power to understand what’s happening inside your system without guessing.
Log every transaction by reference
Track every webhook event
Store every quote, expiry, and result
Build internal dashboards before you need them
Alert early, investigate fast, and design for transparency
