Overview

Webhook notifications in SIBS Payment Gateway (SPG) are delivered using an asynchronous, best-effort model. This means that delivery is not guaranteed to occur exactly once, nor in a specific order.

To ensure reliable processing, merchant systems must be designed to handle retries, duplicated notifications, and potential delays in delivery.

This section describes the delivery behavior of webhooks and the required strategies to safely process them in production environments.

Webhook Delivery Model

SIBS Payment Gateway sends webhook notifications using HTTP POST requests to the configured merchant endpoint.

Key Characteristics

• Asynchronous delivery
  Notifications are sent independently of the original transaction request
• No ordering guarantee
  Events may arrive out of sequence
• At-least-once delivery
  The same notification may be delivered multiple times
• Best-effort delivery
  Delivery depends on network conditions and endpoint availability

Webhook delivery should therefore be treated as an event notification mechanism. When the webhook contains a final paymentStatus, that status can be used for business processing.

Acknowledgement and Response Handling

HTTP 200 OK
{
    "statusCode": "000",
    "statusMsg": "Success",
    "notificationID": "9879b792-1946-4e52-a751-b745a7af5dfa"
}

To confirm successful delivery, the merchant endpoint must return HTTP 200 OK and a JSON response body containing:

• statusCode: "000"
• statusMsg: "Success"
• notificationID: the same notificationID received in the webhook payload

Important Rules

• Any response different from HTTP 200 OK, or a response body not matching the expected acknowledgement structure (including incorrect notificationID), is considered a delivery failure
• Timeouts are treated as failures
• Slow responses may trigger retries

The endpoint should acknowledge the webhook as quickly as possible and defer processing to asynchronous mechanisms.

The notificationID in the response must exactly match the notificationID received in the webhook payload.

 

Returning HTTP 200 without the expected response body, or with an incorrect notificationID, may result in the notification being considered not acknowledged and retried by SIBS.

Retry Mechanism

If a webhook delivery fails, SPG will attempt to resend the notification.

Typical Retry Scenarios

• Endpoint returns a response different from HTTP 200 OK, or a response body not matching the expected acknowledgement structure
• Endpoint is unavailable
• Network errors
• Request timeout

Expected Behavior

• Multiple delivery attempts for the same event
• Increasing delays between retries may occur depending on the SPG retry strategy and operational conditions

Duplicate Notifications

Due to the retry mechanism and delivery model, the same webhook may be received multiple times.

Duplicate notifications are expected behavior and must be handled through safe idempotent processing mechanisms.

Failure to handle duplicates correctly may result in:

• Duplicate order updates
• Incorrect business state transitions
• Inconsistent system behavior

Idempotency Strategy

Webhook processing must be idempotent, meaning that processing the same event multiple times produces the same result.

Recommended Identifier

Use transactionID as the primary identifier for idempotent processing.

The notificationID may additionally be used to detect duplicate deliveries of the same webhook event, while transactionID should remain the authoritative transaction correlation identifier.

Implementation Approach

Basic Idempotency Model

1. Receive webhook
2. Extract transactionID
3. Check if already processed
4. If processed → ignore
5. If not processed → process and store

Recommended Enhancements

• Persist processed transaction identifiers
• Store processing status (e.g., success, failed)
• Allow safe reprocessing in case of internal failures

Persist idempotency and processing state information in durable storage to ensure safe recovery across service restarts, failover events, or infrastructure disruptions.

Processing Order Considerations

Since webhooks may arrive out of order:

• Do not assume chronological sequence
• Always evaluate the current transaction state before applying updates

Use webhook events as triggers and use Status Inquiry before applying critical business logic when the webhook does not provide a final state or when additional confirmation, recovery, or reconciliation is required.

Detailed consistency and reconciliation strategies are described in E.1.8 – Webhooks vs Status Inquiry (Consistency Model) and E.2.6 – Consistency Model: Query vs Webhook.

Resilience and Recovery

To ensure robust processing:

• Combine webhook handling with periodic reconciliation
• Use the Status Inquiry APIs to recover from missed or delayed events
• Implement monitoring for failed or unprocessed notifications

Detailed polling strategies, reconciliation guidance, and operational recovery patterns are provided in E.2.5 – Polling Strategy and Best Practices and E.2.7 – Reconciliation Patterns.

Summary

SPG webhook delivery follows an asynchronous, at-least-once model, which requires careful handling on the merchant side.

A production-ready implementation must:

• Acknowledge notifications with HTTP 200 OK and the expected JSON response body:
  • statusCode: "000"
  • statusMsg: "Success"
  • notificationID: <original notificationID>
• Handle retries and duplicate deliveries
• Implement idempotent processing using transactionID
• Support out-of-order events
• Use the Status Inquiry APIs to confirm the final transaction state when no final webhook is available or when additional confirmation, recovery, or reconciliation is required

This ensures reliable and consistent transaction processing across all payment flows.