XPayLabs Webhook Event Types — Complete Reference

Complete reference for all XPayLabs webhook event types — order events (PENDING, SUCCESS, EXPIRED, FAILED) and collection events (PENDING, SUCCESS, FAILED).

XPayLabs sends webhook notifications based on the NotifyType enum. Each notification corresponds to a change in state of an order or a collection sweep.

Event Types

Event Type	Triggered When	Payload
ORDER_PENDING	A new order is created and is awaiting customer payment	NotifyOrder
ORDER_PENDING_CONFIRMATION	A blockchain transaction is detected but awaiting confirmations	NotifyOrder
ORDER_SUCCESS	Payment confirmed and order completed successfully	NotifyOrder
ORDER_EXPIRED	Order expired before payment was received	NotifyOrder
ORDER_FAILED	Payment transaction failed	NotifyOrder
COLLECT_PENDING	Collection sweep (hot-to-cold transfer) is initiated	NotifyCollect
COLLECT_SUCCESS	Collection sweep completed successfully	NotifyCollect
COLLECT_FAILED	Collection sweep failed	NotifyCollect

---

Order Events (ORDER_*)

ORDER_PENDING

Sent when a collection or payout order is created and is awaiting the next action (customer payment for collections, processing for payouts).

{
  "sign": "a1b2c3d4e5f6...",
  "timestamp": 1717000000,
  "nonce": "nonce_001",
  "notifyType": "ORDER_PENDING",
  "data": {
    "orderId": "order_1042",
    "uid": "user_42",
    "orderType": "COLLECTION",
    "status": "PENDING",
    "reason": null,
    "amount": "250.00",
    "actualAmount": null,
    "fee": "0.00",
    "transaction": null
  }
}

ORDER_PENDING_CONFIRMATION

Sent when a blockchain transaction is detected but has not yet reached the required number of block confirmations. The transaction field is populated with the detected transaction details.

{
  "sign": "a1b2c3d4e5f6...",
  "timestamp": 1717000050,
  "nonce": "nonce_002",
  "notifyType": "ORDER_PENDING_CONFIRMATION",
  "data": {
    "orderId": "order_1042",
    "orderType": "COLLECTION",
    "status": "PENDING_CONFIRMATION",
    "amount": "250.00",
    "actualAmount": "250.00",
    "fee": "0.00",
    "transaction": {
      "chain": "TRON",
      "symbol": "USDT",
      "txid": "a1b2c3d4e5f6...",
      "from": "TXyz...",
      "to": "TWkKZkmuB8DpVeiMoHiKf99ZoFHzk73CqR",
      "amount": "250.00",
      "blockNum": 12345678,
      "confirmedNum": 1,
      "status": "PENDING",
      "timestamp": 1717000045
    }
  }
}

ORDER_SUCCESS

Sent when the payment is fully confirmed (required block confirmations reached) or a payout completes successfully.

{
  "sign": "a1b2c3d4e5f6...",
  "timestamp": 1717000100,
  "nonce": "nonce_003",
  "notifyType": "ORDER_SUCCESS",
  "data": {
    "orderId": "order_1042",
    "orderType": "COLLECTION",
    "status": "SUCCESS",
    "amount": "250.00",
    "actualAmount": "250.00",
    "fee": "0.00",
    "transaction": {
      "chain": "TRON",
      "symbol": "USDT",
      "txid": "a1b2c3d4e5f6...",
      "from": "TXyz...",
      "to": "TWkKZkmuB8DpVeiMoHiKf99ZoFHzk73CqR",
      "amount": "250.00",
      "confirmedNum": 19,
      "status": "SUCCESS",
      "timestamp": 1717000045
    }
  }
}

ORDER_EXPIRED

Sent when an order reaches its expiry time without receiving the required payment.

{
  "sign": "a1b2c3d4e5f6...",
  "timestamp": 1717086401,
  "nonce": "nonce_004",
  "notifyType": "ORDER_EXPIRED",
  "data": {
    "orderId": "order_1042",
    "orderType": "COLLECTION",
    "status": "EXPIRED",
    "reason": "Order expired",
    "amount": "250.00",
    "actualAmount": null,
    "fee": "0.00",
    "transaction": null
  }
}

ORDER_FAILED

Sent when a payout transaction fails or a collection transaction is rejected by the blockchain.

{
  "sign": "a1b2c3d4e5f6...",
  "timestamp": 1717000200,
  "nonce": "nonce_005",
  "notifyType": "ORDER_FAILED",
  "data": {
    "orderId": "payout_001",
    "orderType": "PAYOUT",
    "status": "FAILED",
    "reason": "Insufficient balance",
    "amount": "50.00",
    "actualAmount": "0.00",
    "fee": "0.00",
    "transaction": null
  }
}

---

Collection Events (COLLECT_*)

Collection events are sent when the gateway performs automatic hot-to-cold wallet sweeps (settlement). These are distinct from order events — they relate to the internal movement of funds between the gateway’s wallets.

Event Type	Triggered When
COLLECT_PENDING	A sweep from the hot wallet to the cold wallet is initiated
COLLECT_SUCCESS	The sweep transaction confirmed on-chain
COLLECT_FAILED	The sweep transaction failed

---

Best Practices

1. Respond with 200 quickly. Return 200 OK immediately and process the event asynchronously in a background worker.

2. Verify the signature. Always validate the sign field using your webhook-secret before acting on any event.

3. Deduplicate with nonce. The same event may be delivered more than once. Store processed nonces in your database and skip duplicates.

4. Check notifyType first. Route to different handlers based on the event type.

5. Handle ORDER_PENDING_CONFIRMATION. Use this event to show “payment detected” in your UI before the transaction is fully confirmed.