Webhooks: Real-Time Crypto Payment Notifications

​

How do 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.

​

What is the webhook payload format?

​

What webhook event types are available?

​

Order Events

​

Collection (Settlement) Events

​

Signature Verification

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

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.