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

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 (implementation-dependent)

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 safely.

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.

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

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 confirm the final state using the status API before applying critical business logic.

Resilience and Recovery

To ensure robust processing:

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

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 API to confirm final transaction state

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