Skip to content

Webhooks ​

BITXpay delivers subscribed events to your webhook URL using HTTP POST. Set up a publicly reachable HTTPS endpoint, then configure its URL, secret, and active event subscriptions in your dashboard.

Event types ​

The backend defines these payment and subscription event codes. Discover the active event IDs in your environment through the dashboard or GET /webhooks/events using your dashboard session.

Event typeMeaning
payment_link.createdPayment link created
payment.succeededPayment received successfully
payment.partial_succeededPartial payment received
transaction.overpaidOverpayment received
payment.failedPayment failed
payment.expiredPayment link expired
refund.initiatedRefund requested
refund.succeededRefund completed
subscription_plan.createdSubscription plan created
subscription_invitation.createdSubscription invitation created
subscription.createdSubscription created
subscription.renewedSubscription renewed
subscription.renewal_failedSubscription renewal failed

Availability depends on the active event catalog, enabled subscriptions, and the operation that produces the event. See Webhook Event Data for every field, omission rule, and producer-specific example. Some defined subscription events have no automatic producer in this checkout.

Webhook payload structure ​

json
{
  "id": "558e008e-a31c-4fe8-8c81-284ece730cdf",
  "event_type": "payment.succeeded",
  "event_id": "3f01958c-8f10-4982-87f9-c129f60531b5",
  "timestamp": "2026-11-16T12:00:00Z",
  "data": {
    "event_code": "payment.succeeded",
    "customer_email": "customer@example.com",
    "customer_name": "Alex Customer",
    "link_id": "INV-EIRCEI-DQ",
    "payment_id": "22222222-2222-2222-2222-222222222222",
    "amount": "100.50",
    "currency": "USD",
    "transaction_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "network": "Ethereum",
    "asset": "",
    "fees": "",
    "received_at": "2026-11-16 12:00:00 +0000 UTC"
  }
}

This example shows the common envelope. data contains the original event-specific payload, including event_code and any fields emitted for that event. webhook_metadata is declared only for payment_link.created, subscription.created, and subscription_invitation.created. It is not automatically copied into payment success, partial payment, overpayment, expiry, or refund events. See all payloads.

FieldDescription
idDelivery identifier, newly generated on each attempt
event_typeEvent code; use this to choose your handler
event_idNotification event definition ID
timestampDelivery time in RFC 3339 format
dataEvent-specific data

Verifying webhook signatures ​

Deliveries with a configured secret include:

http
Content-Type: application/json
X-Webhook-Signature: sha256=<64 lowercase hexadecimal characters>
X-Webhook-Timestamp: <Unix time in seconds>
X-Webhook-Event: payment.succeeded

X-Webhook-Event is included when the event definition is loaded. Authenticate the body using X-Webhook-Signature, then read the signed event_type field. Compute HMAC-SHA256 over the raw request body bytes using your webhook secret. The signature has a literal sha256= prefix. The timestamp header is separate from the HMAC input; the body's timestamp is covered by the signature.

javascript
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);
python
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)

Configure a secret and reject missing or invalid signatures. Parse JSON after verification. See Integration Webhooks for handling guidance.

Retries and duplicate handling ​

HTTP 200–299 acknowledges delivery. Connection failures, timeouts, and other status codes cause retries until the configured attempt limit is reached. The backend defaults to five total attempts and a 10-second request timeout. With the default 1-second initial delay and 2× multiplier, retries are scheduled approximately 2, 4, 8, and 16 seconds after failed attempts, with ±10% jitter. Scheduling/worker load can delay actual delivery. The delay is capped at one hour before jitter, and all these settings are configurable.

Store or durably enqueue the verified event before returning 2xx. Deduplicate business changes by the resource and transition in data, such as a payment/transaction reference plus the event type. Do not use only id (it changes on retries) or event_id (shared by all deliveries of an event type). Do not assume delivery order.

Webhook management ​

Webhook management uses your authenticated dashboard session, rather than merchant API-key signatures. All paths below are relative to /api/v1. Use the dashboard for setup when integrating the Merchant API.

MethodPathPurpose
GET/webhooks/eventsDiscover active event definitions and IDs
POST/webhooks/Register a webhook
GET/webhooks/List webhooks
GET/webhooks/:idRetrieve a webhook
PUT/webhooks/:idUpdate URL, secret, status, or subscriptions
DELETE/webhooks/:idRemove a webhook
GET/webhooks/activityInspect delivery activity
GET/webhooks/pollPoll delivery events
POST/webhooks/regenerate-secretRegenerate the shared secret
POST/webhooks/validate-secretValidate the shared secret
POST/webhooks/subscriptions/updateToggle existing subscriptions
POST/webhooks/notifications/registerRegister a test event
POST/webhooks/notifications/acknowledgeAcknowledge a job for testing

Registration body:

json
{
  "url": "https://example.com/webhook",
  "event_subscriptions": [
    {
      "id": "3f01958c-8f10-4982-87f9-c129f60531b5",
      "is_active": true
    }
  ]
}

Use actual event IDs from /webhooks/events. An omitted is_active defaults to false. Omitting subscriptions creates inactive subscriptions to the active catalog, so enable the desired events explicitly. The first webhook gets a generated shared secret; later webhooks reuse it. See Webhook Management for complete request/response contracts, shared-secret behavior, and polling.

Testing webhooks ​

Use the authenticated test-notification API to send any supported event with its exact payload. Run one of the sample handlers locally and expose port 3000 through your development tunnel. Configure the resulting HTTPS URL in the dashboard. Trigger an enabled payment/subscription event and inspect its delivery activity. A temporary webhook inspection URL can also help inspect payloads, but use a handler with signature verification for your integration.

If delivery fails, check public reachability, your configured secret, the raw-body parser, the sha256= prefix, and the HTTP response code. Inspect request and response details in the dashboard's activity view.