Production-ready integrations must ensure that webhook notifications are processed reliably, consistently, and safely, regardless of delivery conditions.

In SIBS Payment Gateway (SPG) integrations, webhooks are a primary mechanism for propagating asynchronous transaction state changes. However, webhook delivery operates under distributed system constraints, where delivery is not guaranteed to be single, ordered, or immediate.

A correct implementation must therefore guarantee that webhook processing remains deterministic, idempotent, and reconciliation-safe, even under adverse conditions.

Webhook Delivery Characteristics

Webhook delivery must be treated as inherently non-deterministic.

In practice, notifications may:

• Be delivered multiple times (duplicate delivery)
• Arrive out of order relative to transaction state progression
• Be delayed due to network or processing conditions

A production-ready system must not assume:

• Exactly-once delivery
• Ordered delivery
• Immediate delivery

Instead, webhook handling must be designed to tolerate all of the above conditions without impacting correctness.

See E.1 – Webhooks (Notifications) for notification structure and delivery behavior.

Idempotent Webhook Processing

Webhook processing must be strictly idempotent, ensuring that repeated processing of the same notification produces no additional side effects.

This requires:

• Detection of previously processed notifications (e.g., via notificationID)
• Safe reprocessing logic that does not duplicate business actions
• Webhook replay handling must also prevent repeated downstream processing, duplicate order fulfillment, and inconsistent business-side effects
• Persistence of processing outcomes

Repeated delivery of the same notification must not result in:

• Duplicate updates to transaction state
• Repeated execution of business logic
• Inconsistent system behavior

See F.6.2 – Transaction Idempotency and Duplicate Protection for idempotency principles.

Order-Independent Processing

Webhook notifications may not arrive in chronological order.

A production-ready system must therefore:

• Process events independently of delivery order
• Validate state transitions before applying updates
• Prevent invalid or regressive transitions (e.g., Success → Pending)

Event processing must ensure that:

• Only valid forward state transitions are applied
• Final states are not overridden by earlier or delayed events

This guarantees consistency even when notifications are received out of sequence.

See F.3 – Success and Error Scenarios for valid state interpretation and transitions.

Separation Between Event Processing and Transaction-State Validation

Figure – Reliable Webhook Processing and Transaction-State Validation

Webhook notifications must be decrypted, validated, correlated, and checked against the expected transaction lifecycle before they are used to update transaction state.

A correct implementation:

• Uses webhooks to initiate internal processing
• Confirms final transaction state when required via the Status Inquiry
• Uses Inquiry Details responses where extended transaction investigation, historical analysis, or reconciliation validation is required
• Ensures alignment between event-driven updates, internal transaction state, and confirmed transaction-state data

This separation is essential to:

• Avoid inconsistencies caused by delayed or duplicated notifications
• Ensure correct final state determination

Temporary discrepancies may exist between webhook notifications, Status Inquiry responses, Inquiry Details responses, and internal Merchant system state during asynchronous processing windows.

See F.6 – Production Readiness Guidelines and F.6.3 – Asynchronous Flow Readiness for transaction-state consistency and reconciliation principles.

Error conditions communicated through webhook payloads must be interpreted using the same classification model defined in C.5 – Status Codes and Error Codes Mapping and C.6 – Error Payloads and Handling Guidelines.

Resilience to Delivery Failures

Webhook delivery may fail or be temporarily unavailable.

A production-ready system must:

• Tolerate temporary unavailability of webhook endpoints
• Ensure that missed or delayed notifications do not result in lost transaction state

This requires:

• Implementing fallback mechanisms (e.g., Status Inquiry / Get Status confirmation when required)
• Ensuring that all transactions can be eventually reconciled
• Webhook delivery failures, repeated retries, unresolved asynchronous states, and reconciliation inconsistencies should be actively monitored and alerted operationally

Failure to account for delivery issues may result in:

• Incomplete transaction processing
• Missing state updates
• Reconciliation discrepancies

Retry strategies must be aligned with error classification: temporary failures (statusCode = Txxxx) may be retried, while validation or business errors (statusCode = Exxxx) must not be retried automatically.

Processing Isolation and Performance

Webhook handling must be designed to avoid impacting system stability.

A correct implementation should:

• Process notifications asynchronously from request/response flows
• Avoid long-running operations during webhook handling
• Ensure fast acknowledgment of webhook reception to avoid unnecessary retries

This prevents:

• Timeouts in webhook delivery
• Repeated delivery due to delayed responses
• Cascading failures in high-load scenarios

Production environments should also monitor webhook-processing backlogs, delayed event accumulation, and queue saturation conditions that may impact asynchronous consistency.

Webhook notifications must also be validated according to the configured security and authenticity verification mechanisms before business processing is initiated.

Consistency Across Webhook and Internal State

Webhook processing must maintain consistency between:

• SPG transaction state
• Internal system state
• Downstream business processes

This requires:

• Controlled application of state updates
• Prevention of conflicting or duplicate changes
• Alignment with idempotency and asynchronous processing rules

Consistency must be preserved even under:

• Duplicate notifications
• Delayed delivery
• Partial system failures

See F.5 – Logging and Monitoring Best Practices for webhook observability, monitoring, correlation, and operational diagnostics guidance.

Final Consideration

Webhook reliability is a critical component of asynchronous flow correctness.

A production-ready integration ensures that:

• Webhook delivery conditions do not impact correctness
• Notifications are processed safely, idempotently, and independently
• Final transaction state is determined from validated final paymentStatus data, or through Status Inquiry when confirmation, recovery, or reconciliation is required
• No transaction state is lost, duplicated, or inconsistently applied across systems

Systems that treat webhooks as guaranteed, ordered, or sufficient as final confirmation signals will inevitably produce incorrect outcomes in production environments.