Overview

Webhook processing in SIBS Payment Gateway (SPG) must be designed to operate correctly under failure conditions, repeated delivery attempts, and asynchronous execution constraints.

This section defines how integrators must handle:

• delivery failures
• retry behavior
• duplicate notifications
• idempotent processing

The objective is to ensure that webhook handling remains consistent, reliable, and safe, even when operating under non-ideal conditions.

Failure Scenarios in Webhook Processing

Webhook delivery and processing may fail at different stages, including:

• network or connectivity issues
• endpoint unavailability
• delayed or missing responses
• invalid acknowledgement responses
• internal processing errors

These failures may prevent SPG from confirming successful delivery and can trigger retry mechanisms.

Additionally, SPG provides webhook delivery failure and system error notifications through the SIBS Backoffice configuration, typically delivered via email. These notifications are operational alerts and are not part of the webhook delivery mechanism itself. They must be integrated into monitoring and incident management processes to ensure visibility over webhook delivery issues.

Configuration of these notifications is described in E.1.7 Webhook Configuration (SIBS SPG Backoffice).

These notifications do not replace retry behavior and must not be used as a trigger for business processing logic or state transitions.

Retry Behavior and Delivery Guarantees

SPG may retry webhook delivery when:

• no response is received within the expected time
• a non-200 HTTP status is returned
• the acknowledgement payload is invalid
• connectivity issues occur

Retry behavior is managed by SPG and is not controlled by the merchant system.

Key characteristics of retry behavior:

• the same webhook may be delivered multiple times
• retries may occur after delays
• delivery order is not guaranteed
• duplicate delivery must be expected

Webhook processing must therefore be designed under the assumption that any notification may be delivered more than once.

Idempotent Processing Model

To ensure correct behavior under repeated delivery, webhook handling must be idempotent.

Idempotency ensures that:

• the same notification can be processed multiple times without side effects
• duplicate events do not result in duplicate business actions
• system state remains consistent regardless of delivery repetition

The notificationID field must be used as the primary idempotency key.

Required behavior:

• store processed notificationID values
• check for prior processing before executing business logic
• ignore duplicates safely
• always return a valid acknowledgement response

This model guarantees safe operation under SPG retry conditions.

Idempotent Processing Flow

This flow ensures that duplicate notifications do not lead to inconsistent system behavior.

Separation of Acknowledgement and Processing

Webhook acknowledgement must remain independent from processing outcomes.

Correct behavior requires:

• always acknowledge valid webhook reception
• do not delay acknowledgement due to processing
• do not return error responses for recoverable processing failures
• handle retries internally

This ensures that SPG retry behavior is not triggered unnecessarily.

This model is consistent with the acknowledgement principles defined in F.10.2 Webhook Acknowledgement Handling.

Internal Retry Strategy

Failures during internal processing must be handled within the merchant system, not through webhook acknowledgement behavior.

Recommended approach:

• implement controlled retry mechanisms for processing failures
• use queues or background workers
• ensure retries are safe and idempotent
• avoid immediate repeated execution loops

Typical retry scenarios include:

• temporary database failures
• transient external service errors
• temporary inconsistencies in dependent systems

Internal retries must ensure eventual consistency without compromising data integrity.

Handling Out-of-Order and Delayed Events

Webhook delivery does not guarantee ordering.

As a result:

• notifications may arrive out of sequence
• intermediate states may be received after final states
• delayed events may no longer be relevant

To handle this correctly:

• always validate current transaction state using the Status API
• do not rely on webhook order
• ensure state transitions are consistent and monotonic

This behavior aligns with the consistency model described in F.10.3 End-to-End Webhook Processing Scenario (Including Status Reconciliation).

Monitoring and Operational Visibility

Webhook failures and retries must be observable and traceable.

Recommended practices:

• log all webhook receptions and responses
• log decryption and processing outcomes
• track retry attempts and duplicate notifications
• monitor webhook delivery failure and system error notifications configured in the SIBS Backoffice

Operational visibility must ensure that webhook delivery issues are detected, diagnosed, and resolved without impacting transaction consistency.

Final Consideration

Failure handling, retry management, and idempotency are core requirements for any production-grade SPG integration.

A correct implementation ensures that:

• webhook delivery failures do not lead to data inconsistency
• duplicate notifications do not produce duplicate outcomes
• retry mechanisms operate safely and predictably
• asynchronous processing remains resilient under failure conditions

By applying the principles described in this section, integrators ensure that webhook handling remains robust, reliable, and consistent, even in the presence of failures and non-deterministic delivery behavior.