XPayLabs Webhooks — Real-Time Blockchain Payment Notifications

XPayLabs sends signed HTTP callbacks to your server when on-chain payment events occur. Learn how webhooks work, the payload format, and how to verify signatures.

Webhooks are the primary way your server learns about payment events in real-time. Instead of polling the gateway API, you register a callback URL and XPayLabs sends signed POST requests whenever an order or collection changes state.

How Webhooks Work

1. You configure a callback-url and webhook-secret in the gateway configuration.
2. When an event occurs (e.g., a payment is detected), the gateway constructs a NotifyPayload and sends it to your URL.
3. Your server verifies the HMAC-SHA256 signature and processes the event.

Payload Structure

Every webhook follows the NotifyPayload format:

Field	Type	Description
sign	string	HMAC-SHA256 of the data field, signed with your webhook secret
timestamp	integer	Unix timestamp of the event
nonce	string	Unique event identifier for deduplication
notifyType	string	The event type identifier
data	object	The event payload (NotifyOrder or related object)

Event Types

Order Events

Event	Description
ORDER_PENDING	Order created, awaiting payment
ORDER_PENDING_CONFIRMATION	Transaction detected, awaiting block confirmations
ORDER_SUCCESS	Payment fully confirmed
ORDER_EXPIRED	Order expired without payment
ORDER_FAILED	Order failed

Collection (Settlement) Events

Event	Description
COLLECT_PENDING	Hot-to-cold sweep initiated
COLLECT_SUCCESS	Sweep completed successfully
COLLECT_FAILED	Sweep transaction failed

Signature Verification

Every webhook includes a sign field computed as:

sign = HEX(HMAC-SHA256(JSON.stringify(data), webhook_secret))

You must verify this signature before acting on any webhook. See the Webhook Reference for code examples in Node.js, Python, and other languages.

Delivery Guarantees

• At-least-once delivery. The same event may arrive more than once under rare conditions. Use the nonce field for deduplication.
• Retry with backoff. If your endpoint returns a non-2xx status or times out, XPayLabs retries with exponential backoff.
• Ordering. Events for a single order are delivered in sequence. Events across different orders may arrive out of order.

Best Practices

1. Always verify the signature. Never process a webhook without validating the sign field.
2. Return 200 quickly. Acknowledge receipt immediately and process the event asynchronously.
3. Deduplicate with nonce. Store processed nonces to handle duplicate deliveries safely.
4. Use ORDER_PENDING_CONFIRMATION for early UX. Show “payment detected” in your UI before the transaction is fully confirmed.
5. Handle ORDER_SUCCESS for fulfillment. This is the signal to deliver goods or services.