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.
In SPG, webhook notifications are sent for final states, except for Multibanco Reference generation, where a Pending notification may also be sent when the reference is generated.
Webhooks are a fundamental component of SPG integrations and must be implemented to ensure that the merchant system is informed about final transaction states and applicable asynchronous notification events 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
- Support safe handling of duplicate notifications, retry scenarios, and out-of-order event delivery through idempotent processing mechanisms
Webhook notifications should be processed as transaction event notifications. When the webhook contains a final paymentStatus, that status can be used for business processing. Status Inquiry should be used when additional confirmation, reconciliation, recovery from missed notifications, or investigation of inconsistencies is required.
For the transaction query model and reconciliation strategies between notifications and transaction state queries, see E.2 Status Inquiry / Get Status.
Error conditions and response codes received in webhook payloads must be interpreted according to the model defined in:
Webhook payloads contain technical status information (returnStatus), but correct handling requires applying the classification and interpretation rules defined in these chapters.
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, monitoring, retry management, and logging webhook events - Backoffice configuration
How to configure webhook endpoints in the SPG Backoffice
Operational monitoring, webhook delivery visibility, retry analysis, and notification troubleshooting through 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.