> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpaylabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks: Real-Time Crypto Payment Notifications

> XPayLabs webhooks deliver real-time notifications for order and collection status changes. Configure callback URLs and verify HMAC signatures for secure integration.

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?

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?

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)                |

## What webhook event types are available?

### 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](/api-reference/webhooks/overview) 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.