Overview

This chapter provides practical and implementation-oriented examples of webhook handling in SIBS Payment Gateway (SPG) integrations, focusing on how asynchronous notifications are received, processed, and incorporated into the transaction lifecycle.

In SPG, transaction processing is not limited to synchronous API interactions. A significant portion of payment flows rely on asynchronous state transitions, where the final outcome of a transaction is delivered after the initial request through external processing, customer interaction, or delayed processing.

Webhook notifications represent the primary asynchronous mechanism for communicating transaction-state changes to the merchant system, as defined in the E.1 – Webhooks (Notifications) section.

Final transaction-state confirmation and reconciliation should use Status Inquiry / Get Status when confirmation, recovery, or inconsistency resolution is required. See E.2 – Status Inquiry / Get Status.

When extended operational diagnostics are required during webhook lifecycle analysis or troubleshooting, additional visibility may leverage Inquiry Details as described in E.2.10 – Inquiry Details API.

Role of Webhooks in the Transaction Lifecycle

Webhook handling must be implemented as a core component of the transaction execution model, not as an auxiliary integration feature.

A correct implementation requires the ability to:

• Receive and validate external notifications, including validation of structure, headers, and authenticity as defined in the E.1 – Webhooks (Notifications) section
• Process encrypted payloads into usable data structures
• Correlate notifications with the corresponding transaction using the transactionID
• Execute processing logic in an idempotent and controlled manner
• Handle repeated, delayed, or out-of-order events
• Maintain consistent transaction-state interpretation across all systems

This reflects the operational reality of SPG integrations, where systems must behave correctly under asynchronous and non-deterministic conditions, rather than relying on immediate or single-step outcomes.

Webhook as Event Signal, Not Final State

Webhook notifications provide event-driven visibility of transaction state transitions and must be processed with idempotency, ordering, and reconciliation safeguards.

A notification indicates that a change has occurred, but:

• it may not represent the final state of the transaction
• it may be delivered multiple times
• it may arrive after other system events
• it may temporarily diverge from other transaction-state information sources

For this reason, webhook processing must always be integrated into a broader model that includes state validation and reconciliation, ensuring that final transaction outcomes are confirmed or reconciled through Status Inquiry / Get Status when confirmation, recovery, or inconsistency resolution is required.

Operational Constraints and Processing Requirements

A production-grade webhook integration must operate correctly under the following conditions:

• asynchronous execution and delayed finalization
• repeated delivery of the same notification
• partial failures during processing
• independent evolution of transaction state across systems

This requires webhook handling to be:

• idempotent, ensuring that repeated events do not produce inconsistent results
• order-independent, ensuring correctness regardless of delivery sequence
• resilient, ensuring correct behavior under failure conditions
• traceable, ensuring that each event can be correlated and audited

These characteristics are essential to guarantee consistent transaction processing and prevent incorrect business outcomes.

Error interpretation and retry behavior must follow the model defined in C.5 – Status Codes and Error Codes Mapping and C.6 – Error Payloads and Handling Guidelines.

Implementation Scope of the Examples

The examples in this chapter focus on how webhook interactions are implemented in practice, including:

• reception and decryption of notifications, in accordance with the encryption and transport model defined in the E.1 – Webhooks (Notifications) section
• processing pipelines and execution models
• acknowledgement handling
• reconciliation with transaction state
• handling of retries, duplicates, and failure scenarios

The objective is to demonstrate how webhook processing integrates with the overall SPG execution model, ensuring that asynchronous events are handled in a way that preserves transaction integrity, consistency, and correctness across the full lifecycle.

Final Consideration

Webhook integration is a fundamental element of SPG transaction processing and must be treated as part of the core execution model.

A correct implementation is not defined by the ability to receive notifications, but by the ability to process them reliably under real-world conditions, ensuring that:

• transaction state is correctly interpreted
• events are safely handled regardless of delivery behavior
• final outcomes remain consistent across systems

By applying the patterns illustrated in this chapter, integrators ensure that their systems operate correctly within the SPG asynchronous model, maintaining reliability, consistency, and correctness in production environments.