Callbacks: Risks and Best Practices#

XGateway provides server-to-server callbacks (webhooks) to notify merchants about important events such as transaction state changes, KYC status updates, and chargebacks.

Why Use Callbacks#

Callbacks are the recommended primary integration mechanism for receiving updates from XGateway:

• Near real-time updates — Receive notifications as events happen, without polling.
• Reduced system load — No need for constant API queries; updates arrive when relevant.
• Built-in resilience — Automatic retries with exponential backoff ensure delivery.
• Auditability — All sent callbacks are visible in the Back Office exactly as delivered.

Each callback is signed using SHA-512 with your merchant secret, allowing you to verify authenticity.

Important Disclaimer#

Understanding Callback Risks#

Even when a callback is correct at the time it is emitted, several factors can affect how you receive and interpret it:

1. State May Change After Emission#

A callback reflects system state at the moment it was generated. Between emission and your processing:

• A transaction may progress to a new state (e.g., pending → completed).
• A dispute may be filed against a previously successful payment.
• External factors (chargebacks, reversals, compliance holds) may alter the outcome.

The callback was accurate when sent, but may no longer represent current reality.

2. Out-of-Order Delivery#

Network conditions and retry logic can cause callbacks to arrive in unexpected order:

• A completed callback may arrive before the pending callback.
• Multiple state transitions may be received out of sequence.

Your system must handle this gracefully — never assume arrival order matches event order.

3. Duplicate Deliveries#

Callbacks may be delivered multiple times due to:

• Network timeouts causing retries.
• Your endpoint returning an error or slow response.
• Infrastructure issues on either side.

Design your handlers to be idempotent — processing the same callback twice should produce the same result.

4. Delivery Failures#

If your callback endpoint is unavailable, slow, or returns errors:

• Retries will continue with increasing intervals.
• During this window, your system state may diverge from XGateway.
• You may miss time-sensitive updates.

Recommended Integration Pattern#

Use Callbacks as the Primary Driver#

Build your integration around callbacks for efficiency and responsiveness:

1. Set up callback endpoints for all relevant event types.
2. Process callbacks promptly — update your system based on received events.
3. Acknowledge quickly — return HTTP 200 as soon as the payload is validated and queued; perform heavy processing asynchronously.

Verify Critical States via API#

For high-stakes operations, confirm the latest state before finalizing business actions:

Implementation Checklist#

• [ ] Validate signatures — Verify SHA-512 signature using your merchant secret; reject invalid callbacks.
• [ ] Ensure idempotency — Use transaction IDs and order IDs to deduplicate; handle repeated callbacks safely.
• [ ] Handle out-of-order events — Apply state transitions defensively; ignore apparent regressions unless verified.
• [ ] Log everything — Record all received callbacks and validation results for debugging.
• [ ] Set up monitoring — Alert on repeated failures, signature mismatches, or unexpected patterns.

Polling Guidance#

Callbacks should be your primary mechanism. However, if polling is necessary:

• Avoid high-frequency polling — Use reasonable intervals with exponential backoff.
• Use polling for recovery — Catch up on missed events after outages.
• Prefer event-driven updates — Return to callback-based flow as soon as possible.

Failure Handling and Observability#

• Compare sent vs. received — Use the Back Office to verify what callbacks were sent and troubleshoot discrepancies.
• Implement alerting — Monitor for repeated delivery failures, signature mismatches, or unusual callback volumes.
• Plan for recovery — Have a process to reconcile state after extended outages using API queries.

Exponential Backoff#

XGateway uses an exponential backoff mechanism to retry failed callback deliveries:

• Retry intervals — Geometric progression starting at 1 second, then 2, 4, 8, 16... seconds.
• Maximum attempts — 10 delivery attempts before the callback is marked as failed.
• Auditability — All sent callbacks (including failed ones) are visible in the Back Office for verification.

Summary#

Best practice: Use callbacks as your primary integration mechanism for responsiveness and efficiency. Verify critical states via the API before taking irreversible actions. The API response is the only contractual commitment XGateway makes regarding system state.