Overview

This section describes how to implement a webhook endpoint capable of receiving and handling notifications from SIBS Payment Gateway (SPG).

Webhook handling must be designed to ensure:

• Fast and reliable acknowledgement of notifications
• Secure handling of incoming data
• Idempotent and resilient processing
• Clear separation between reception and business logic

A correct implementation requires a decoupled architecture, where webhook reception is lightweight and processing is handled asynchronously.

Webhook Endpoint Requirements

The merchant system must expose an HTTP endpoint to receive webhook notifications.

Technical Requirements

• Accept HTTP POST requests
• Accept JSON payloads (encrypted at transport level)
• Be publicly accessible
• Support HTTPS (TLS 1.2 or higher)
• Return HTTP 200 OK with the expected webhook acknowledgement response body

Webhook Reception Flow

The webhook endpoint must follow a well-defined processing pipeline.

Step-by-Step Handling

1. Receive Request

• Accept the HTTP POST request
• Read headers and raw request body

2. Read Required Metadata

• Extract relevant headers required for processing
• Preserve the raw request body for traceability

3. Decrypt Payload

Webhook payloads are received in encrypted format and must be decrypted before they can be processed.

4. Validate Payload Structure

After decryption:

• Parse JSON payload
• Validate presence of required fields (e.g., transactionID, paymentStatus)
• Ensure payload consistency before further processing

5. Persist or Enqueue Event

Before returning a response:

• Store the webhook payload (recommended)
• Or enqueue the event into a processing system (queue, event bus, etc.)

This ensures that the event is not lost even if downstream processing fails.

6. Immediate Acknowledgement

Return:

• HTTP 200 OK with the expected JSON response body containing:
  • statusCode: "000"
  • statusMsg: "Success"
  • notificationID equal to the received webhook notificationID

The acknowledgement response must follow the exact structure defined in E.1.3 Webhook Delivery, Retries and Idempotency. Returning HTTP 200 without the expected response body may result in the notification being considered not acknowledged.

Critical Implementation Rule

Do NOT:

• Call SPG APIs (including /status)
• Perform database-heavy operations synchronously
• Execute business workflows before responding
• Block the HTTP response

Asynchronous Processing

All business logic must be executed outside the request lifecycle.

Error Handling Strategy

During Reception

• Always return HTTP 200 OK with the expected acknowledgement response body if the event is successfully stored
• Do not fail the webhook due to internal processing errors

During Async Processing

• Implement retry mechanisms for internal failures
• Log errors and allow reprocessing
• Ensure idempotent handling

Idempotency Considerations

Webhook notifications may be delivered multiple times.

Recommended Approach

• Use transactionID as unique identifier
• Store processed transactions
• Ignore duplicates or ensure safe reprocessing

Logging and Traceability

The system should log:

• Raw webhook payload (before and after decryption if applicable)
• Reception timestamp
• Processing status
• Correlation identifiers:
  • transactionID
  • merchantTransactionId

Common Implementation Pitfalls

• Performing synchronous processing in the webhook endpoint
• Calling SPG APIs before responding
• Not handling encrypted payloads correctly
• Assuming webhook delivery order
• Not persisting webhook events
• Not validating final transaction state

Summary

Webhook handling must follow a decoupled and asynchronous model:

• Receive and acknowledge notifications immediately
• Decrypt and validate payloads before processing
• Persist events before responding
• Process events asynchronously
• Validate transaction state using the Status API

This approach ensures scalable, resilient, and production-ready webhook handling in SPG integrations.