XPayLabs Webhook Event Types — Complete Reference

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

Respond with 200 quickly. Return 200 OK immediately and process the event asynchronously in a background worker.
Verify the signature. Always validate the sign field using your webhook-secret before acting on any event.
Deduplicate with nonce. The same event may be delivered more than once. Store processed nonces in your database and skip duplicates.
Check notifyType first. Route to different handlers based on the event type.
Handle ORDER_PENDING_CONFIRMATION. Use this event to show “payment detected” in your UI before the transaction is fully confirmed.

​Event Types

​Order Events (ORDER_*)

​ORDER_PENDING

​ORDER_PENDING_CONFIRMATION

​ORDER_SUCCESS

​ORDER_EXPIRED

​ORDER_FAILED

​Collection Events (COLLECT_*)

​Best Practices