Documentation Index
Fetch the complete documentation index at: https://neilyan.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
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
- You configure a
callback-url and webhook-secret in the gateway configuration.
- When an event occurs (e.g., a payment is detected), the gateway constructs a
NotifyPayload and sends it to your URL.
- 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))
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
- Always verify the signature. Never process a webhook without validating the
sign field.
- Return 200 quickly. Acknowledge receipt immediately and process the event asynchronously.
- Deduplicate with
nonce. Store processed nonces to handle duplicate deliveries safely.
- Use
ORDER_PENDING_CONFIRMATION for early UX. Show “payment detected” in your UI before the transaction is fully confirmed.
- Handle
ORDER_SUCCESS for fulfillment. This is the signal to deliver goods or services.
