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 and idempotent, 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
• 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 arrival 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 State Authority

Webhook notifications must be used as processing triggers, not as the authoritative source of truth.

A correct implementation:

• Uses webhooks to initiate internal processing
• Confirms final transaction state when required via the Status API
• Ensures alignment between event-driven updates and authoritative state

This separation is essential to:

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

See F.6 Production Readiness Guidelines and F.6.3 Asynchronous Flow Readiness for the authoritative state model.

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 API validation)
• Ensuring that all transactions can be eventually reconciled

Failure to account for delivery issues may result in:

• Incomplete transaction processing
• Missing state updates
• Reconciliation discrepancies

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

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

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 always derived from authoritative sources
• No transaction state is lost, duplicated, or inconsistently applied across systems

Systems that treat webhooks as reliable, ordered, or authoritative will inevitably produce incorrect outcomes in production environments.