🔔Webhooks

Webhooks

Notification Callback

1. Basic Information

1.1 Trigger Conditions

Only invoices created through the API will trigger notification callbacks.

1.2 Callback Mechanism

When Xcash detects an on-chain payment, the system will send callback notifications to the merchant based on the configured notification mode.

2. Notification Modes

The system provides two notification modes, differing in callback trigger timing:

2.1 Fast Mode

  • Trigger Timing: Immediate callback after transaction is on-chain

  • Use Case: Small transactions, pursuing ultimate payment experience

  • Risk Disclosure: Extremely low probability of block rollback exists

  • Risk Protection: For rollbacks of transactions valued under 10 USD, Xcash will fully compensate to merchant balance

2.2 Complete Mode

  • Trigger Timing: Callback after transaction is on-chain and confirmations reach threshold

  • Use Case: Large transactions, requiring absolute security

  • Security Guarantee: Blockchain transaction can no longer be rolled back

2.3 Mode Configuration

Set the Fast Confirmation Threshold on the project configuration page:

  • Value below threshold: Automatically uses fast mode

  • Value greater than or equal to threshold: Automatically uses complete mode

  • Completely disable fast mode: Set threshold to 0

3. Technical Specifications

3.1 Request Format

  • Request Method: POST

  • Content-Type: application/json

  • Request Header Authentication:

    • XC-Appid: Project APPID

    • XC-Nonce: Random number

    • XC-Timestamp: Timestamp

    • XC-Signature: Signature

    • For detailed rules, see API Authentication

3.2 Data Structure

{
  "type": "invoice",
  "data": {
    "sys_no": "INV-202405180001",
    "out_no": "ORDER-20240518001",
    "crypto": "USDT",
    "pay_address": "0xA1b2C3d4E5f6A7b8C9d0eF112233445566778899",
    "pay_amount": "99.85000000"
  },
  "tx": {
    "chain": "bnbchain-mainnet",
    "block": 18234567,
    "hash": "0xaaaa...aaaa",
    "status": "confirmed",
    "is_confirmed": true
  }
}

3.3 Response Requirements

  • Success Criteria: Return HTTP 200 with body as string ok (lowercase)

  • Other Responses: Considered as failure, will trigger retry mechanism

4. Retry and Circuit Breaking

4.1 Retry Strategy

  • Retry Count: Maximum 5 times

  • Backoff Algorithm: Approximately 2^(n+1) seconds (1s, 2s, 4s, 8s, 16s...)

  • Backoff Limit: 120 seconds

4.2 Circuit Breaking Mechanism

  • Trigger Condition: Consecutive failures exceeding 30 times

  • Circuit Breaking Effect: Automatically stops all notifications for the project

  • Recovery Method: Go to console "Project Configuration" and manually switch "Notification Status" to enabled

4.3 Manual Retry

  • Non-Circuit Breaking Scenario: Enter notification event list, select failed event, click "Redeliver"

5. Development Recommendations

5.1 Idempotency Handling

  • Use nonce as idempotency key to ensure the same notification is processed only once

  • Due to retry mechanism, idempotency control is essential

5.2 Recommended Processing Flow

  1. First persist notification content to database

  2. Immediately return HTTP 200 + "ok"

  3. Then asynchronously process invoice business logic

This ensures timeouts and retries won't occur due to time-consuming business processing.

PreviousRetrieveNextWordpress

Last updated