Webhook

The webhook notification system alerts you in real time to payment state changes. Interpreting them correctly is critical to avoid releasing products without confirmation or keeping a customer waiting.

Configuration

• Webhook URL: configured in the dashboard, on the device settings (notification_url).
• Scope: webhooks operate per device. Each device can have its own URL.
• HTTP method: POST.
• Body: JSON.

Headers

POST /your/endpoint HTTP/1.1
Content-Type: application/json
X-NONCE: 1645634942
X-SIGNATURE: 395a6c0294f0896fcc0e5827e926e12308f4fdca5c18da69d3af6879e5c80e2d

• X-NONCE: Unix timestamp in seconds at the moment B4bit Pay generated the signature.
• X-SIGNATURE: hex(HMAC_SHA256(bytes.fromhex(secret_key), nonce_ascii + body_utf8)).

Signature algorithm

signature = hex(HMAC_SHA256(secret_hex → bytes, nonce + body))

• The Secret Key of the device comes from the dashboard in hexadecimal format; decode it to bytes before use.
• nonce is the ASCII timestamp string ("1645634942", not the integer).
• body is the raw request body, unparsed and unmodified (no extra trailing newline).
• The concatenation is nonce + body without separators.

Time window

Caution

Reject any webhook whose X-NONCE differs by more than 15-20 seconds from your server clock. Protects against replay attacks. Sync your server with NTP.

Note: the backend emits the nonce but does not validate incoming time windows (that is solely the receiver’s responsibility). The 15-20 s recommendation is B4bit’s official guidance for integrators.

Retry policy

Danger

B4bit Pay does NOT retry the webhook if your server fails. Confirmed against the backend: a single session.send(request) call without timeout or retry logic.

Operational implication: if your endpoint is down during a state change, the webhook is lost. It will not be delivered a second time.

Recommended mitigations:

1. High availability on the webhook endpoint (reverse proxy, at least 2 workers, health check).
2. Async processing: return HTTP 200 immediately and queue the heavy work (Redis, SQS, etc.).
3. Reconciliation polling — a daily job that queries GET /orders/ for the previous day and cross-references your database by identifier to catch any lost webhooks.
4. Query state directly via GET /orders/info/{identifier} if you detect an “orphan” order or want to confirm the authoritative state.

Idempotency

Deduplicate by identifier + status + edited_at before applying side effects. Even though the backend does not retry, network retries at the TCP level or merchant deployments can cause duplicates in practice.

Official test vector

See Webhook — test vectors for reproducible values you can use to verify your HMAC implementation before connecting to production.

Expected response

Return HTTP 2xx (200/201/202/204) fast — ideally in less than 5 seconds. Process the heavy logic asynchronously.