Webhook Security & Delivery
Webhook Delivery Format
Bitnob webhooks are delivered as HTTP POST requests to the URL you provide in your dashboard or API call.
| Header | Value |
|---|---|
| Content-Type | application/json |
| X-Bitnob-Signature | HMAC-SHA256 hash used to verify the webhook |
| X-Bitnob-Timestamp | UNIX timestamp when the webhook was generated |
| X-Bitnob-Event | Event name (e.g. virtualcard.transaction.debit) |
The body of the request contains the full JSON payload of the event.
Why Signature Verification Matters
To protect against spoofed webhooks or malicious actors sending fake events, you should verify the X-Bitnob-Signature using your Bitnob webhook secret.
Signature Verification Process
Bitnob signs each webhook payload using HMAC SHA-256, with your webhook secret as the key. Here's how to verify the signature:
Read the raw request body (as a string)
Concatenate the X-Bitnob-Timestamp and the raw body, separated by a .
Generate the HMAC SHA-256 digest using your webhook secret
Compare the result to the value in the X-Bitnob-Signature header (constant-time)
Python Example: Verifying Bitnob Webhooks
Note: You must read the raw body, not request.json, to ensure the hash matches exactly.
Security Tips
| Tip | Description |
|---|---|
| Use HTTPS | Never accept webhooks over HTTP. Always use TLS. |
| Keep your secret secure | Do not hard-code secrets in frontend code or public repos. |
| Log all incoming events | Helps with debugging, dispute resolution, or replay. |
| Validate timestamps | Optionally reject events older than 5 minutes to prevent replay attacks. |
| Respond quickly | Always return HTTP 200 as soon as your app accepts the event. |
Retry Behavior
| Behavior | Description |
|---|---|
| Retries | Up to 5 attempts with exponential backoff (e.g. 1s, 2s, 4s...) |
| Timeout | If your server does not respond within 10 seconds, retry is triggered |
| Duplicate Events | Possible — your webhook handlers must be idempotent |
| Failure Logs | Available in your dashboard (coming soon) |
Testing Webhooks
You can test your webhook endpoint in the following ways:
Use the Bitnob Sandbox environment to trigger real test events
Manually simulate webhook payloads using tools like curl or Postman
Replay real events from your dashboard (feature coming)
Example: curl test webhook
