Introduction

Webhooks are the mechanism used by SIBS Payment Gateway (SPG) to notify the merchant system about transaction events, particularly in scenarios where the outcome of a payment is not immediately available.

They enable a push-based communication model, allowing SPG to send near real-time notifications whenever a relevant change occurs in the lifecycle of a transaction. This is especially important for asynchronous payment methods, where user interaction or external processing is required before a final status is reached.

Webhooks are a fundamental component of SPG integrations and must be implemented to ensure that the merchant system is informed about transaction progress and state changes in a timely manner.

Purpose

The purpose of webhooks is to:

• Provide near real-time updates on transaction state changes
• Support asynchronous payment flows
• Reduce dependency on continuous polling
• Enable reactive processing of payment events

However, webhook notifications alone should not be considered as the final source of truth for transaction status.

For critical operations and final state validation, the merchant system must always confirm the transaction status using the dedicated status endpoint.

This ensures consistency, particularly in scenarios involving retries, delayed notifications, or network issues.

Scope of This Section

This section introduces the webhook mechanism and provides a structured approach to understanding and implementing it within an SPG integration.

The detailed documentation is organized into the following topics:

• Webhook structure
  Description of the common payload structure used across notifications
• Webhook variants by payment method
  Specific fields and behaviors depending on the payment method and operation
• Security and validation
  Guidelines for validating and securing webhook notifications
• Retries and idempotency
  Handling delivery retries and ensuring safe processing of repeated events
• Processing and operational best practices
  Recommendations for receiving, handling, and logging webhook events
• Backoffice configuration
  How to configure webhook endpoints in the SPG Backoffice

This structure ensures a clear separation between conceptual understanding and implementation details, enabling teams to progressively build a robust and production-ready webhook integration.