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 do 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.
Every webhook follows the NotifyPayload format:
What webhook event types are available?
Order Events
Collection (Settlement) Events
Signature Verification
Every webhook includes a sign field computed as:
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
- 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.
Last modified on June 26, 2026
