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

Python Webhook Verification

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

Curl Test Webhook