Webhooks
BITXpay sends HTTP POST requests to subscribed webhook URLs. Configure the URL, shared secret, and active events in your dashboard. The Webhooks Guide describes the payload, event codes, retries, and management endpoints.
Verify deliveries
The header is X-Webhook-Signature: sha256=<hex>. Verify HMAC-SHA256 over the exact raw body with your webhook secret before parsing JSON.
import crypto from 'node:crypto';
import express from 'express';
const app = express();
const secret = process.env.WEBHOOK_SECRET;
if (!secret) throw new Error('WEBHOOK_SECRET is required');
export function verifyWebhook(rawBody, signature, webhookSecret) {
if (typeof signature !== 'string' || !/^sha256=[a-f0-9]{64}$/.test(signature)) {
return false;
}
const expected = crypto.createHmac('sha256', webhookSecret).update(rawBody).digest();
return crypto.timingSafeEqual(Buffer.from(signature.slice(7), 'hex'), expected);
}
// Register before express.json() middleware to preserve the signed bytes.
app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
if (!verifyWebhook(req.body, req.headers['x-webhook-signature'], secret)) {
return res.status(401).send('Invalid signature');
}
const event = JSON.parse(req.body.toString('utf8'));
console.log('Webhook:', event.event_type, event.data);
// Durably enqueue the verified event before acknowledging it.
// Apply business changes idempotently using payment/transaction references
// in event.data: delivery id changes on retry; event_id identifies a type.
res.sendStatus(200);
});
app.listen(3000);import hashlib
import hmac
import json
import os
from flask import Flask, request
app = Flask(__name__)
secret = os.environ['WEBHOOK_SECRET']
def verify_webhook(raw_body: bytes, signature: str, webhook_secret: str) -> bool:
expected = 'sha256=' + hmac.new(
webhook_secret.encode('utf-8'), raw_body, hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature.encode('utf-8'), expected.encode('ascii'))
@app.post('/webhook')
def webhook():
raw_body = request.get_data()
signature = request.headers.get('X-Webhook-Signature', '')
if not verify_webhook(raw_body, signature, secret):
return 'Invalid signature', 401
event = json.loads(raw_body)
app.logger.info('Webhook: %s', event['event_type'])
# Durably enqueue before acknowledging. Deduplicate business changes using
# payment/transaction references in event['data'], not the delivery id.
return 'OK', 200
if __name__ == '__main__':
app.run(port=3000)Handle events reliably
Read event.event_type, for example payment.succeeded or payment.failed. Event-specific fields are inside event.data. Use the complete field reference and downloadable examples to map each event to your order model. For engine payment events, payment_id is the link UUID and link_id is an INV-... display reference; refund events use the dispute UUID as payment_id. Partial/overpayment amounts are display token units, while success/failure engine events use the invoice denomination. Metadata is not present on every event.
Return HTTP 2xx after storing or durably enqueueing the verified event. Failed deliveries retry with configurable exponential backoff and jitter. Apply updates idempotently using the business resource and transition in data: id is generated for each delivery attempt, and event_id identifies the notification event definition rather than an individual payment.
Use the dashboard's webhook activity view to inspect attempt status, request payloads, and responses. See Testing Webhooks for local setup.