Overview

This section defines how webhook notifications must be acknowledged by the merchant system, ensuring correct interaction with the SIBS Payment Gateway (SPG) delivery mechanism.

Webhook acknowledgement is not a trivial response operation but a critical part of the delivery contract, directly impacting retry behavior, delivery guarantees, and overall system stability.

A correct acknowledgement implementation ensures that notifications are not unnecessarily retried and that webhook delivery remains reliable under production conditions.

Acknowledgement Response Contract

After successfully receiving and validating a webhook notification, the merchant system must respond with an HTTP 200 status and a specific JSON payload.

Required response:

{
    "statusCode": "000",
    "statusMsg": "Success",
    "notificationID": "<value>"
}

Requirements:

• HTTP status code must be 200
• The response body must be valid JSON
• statusCode must be "000"
• statusMsg must be "Success"
• notificationID must match the value received in the webhook payload

Failure to comply with this response format may result in the notification being treated as not acknowledged.

Timing and Execution Constraints

Acknowledgement must be returned immediately after reception and minimal validation, without waiting for full business processing.

The following constraints apply:

• The response must be sent as quickly as possible
• No blocking operations must occur before responding
• Validation steps performed before acknowledgement must be lightweight and controlled
• Business logic must not delay the response

Webhook handling must therefore follow a model where:

• reception and acknowledgement are synchronous and fast
• processing is asynchronous and decoupled

This approach ensures that SPG receives confirmation promptly and avoids unnecessary retries.

Acknowledgement Flow

The acknowledgement is returned independently of the full processing pipeline, ensuring that delivery confirmation is not impacted by downstream operations.

Impact on Retry Behavior

The acknowledgement response directly influences how SPG handles delivery retries.

• A correct HTTP 200 response with the expected payload indicates successful reception
• Any deviation (non-200 response, invalid payload, timeout) may trigger retry attempts

Retries may occur in scenarios such as:

• delayed response
• incorrect response structure
• missing or incorrect notificationID
• server errors or connectivity issues

For this reason, acknowledgement handling must be implemented with strict correctness and minimal latency.

Idempotency and Safe Acknowledgement

Acknowledgement handling must be compatible with the idempotent processing model described in F.10.1 Webhook Reception, Decryption and Processing Flow.

This implies:

• A notification may be received multiple times
• The system must acknowledge each valid delivery
• Duplicate notifications must not result in duplicate business processing

Acknowledgement confirms receipt, not processing completion.

This distinction is critical:

• A notification can be acknowledged even if processing is deferred
• Processing failures must not prevent acknowledgement
• Retry handling must be managed internally, not through acknowledgement behavior

Common Implementation Errors

Incorrect acknowledgement handling is a frequent source of integration issues.

Common errors include:

• Delaying the response until business processing completes
• Returning non-200 HTTP status codes for valid notifications
• Omitting or altering the notificationID in the response
• Returning an incorrect response structure
• Performing synchronous calls to external APIs before responding

These patterns lead to:

• repeated webhook deliveries
• increased system load
• inconsistent transaction handling

Integration with the Processing Model

Acknowledgement must be integrated into a processing model where:

• reception and validation are performed synchronously
• acknowledgement is returned immediately
• full processing occurs asynchronously

This aligns with the processing model described in F.10.1 Webhook Reception, Decryption and Processing Flow, ensuring that:

• webhook delivery is reliable
• system performance is preserved
• processing remains resilient under load

Final Consideration

Webhook acknowledgement is a contractual obligation in SPG integrations and must be treated as a first-class component of the system design.

A correct implementation ensures that:

• notifications are accepted and confirmed reliably
• retry behavior is controlled and predictable
• system performance is not degraded by synchronous processing
• webhook handling remains consistent under real-world conditions

By implementing acknowledgement handling as described in this section, integrators ensure that webhook delivery operates correctly, supporting a stable, scalable, and production-ready integration model.