Overview

This section provides a concrete and implementation-oriented example of how webhook notifications must be received, decrypted, validated, and processed within a production-grade SIBS Payment Gateway (SPG) integration.

Webhook delivery, encryption model, and required headers are defined in the E.1 Webhooks (Notifications) section. The objective here is to demonstrate how those specifications are applied in a real processing pipeline, ensuring correctness under asynchronous and non-deterministic conditions.

Webhook handling must be implemented as a structured and controlled process, where each step is explicitly defined and validated, rather than as a single-step operation.

End-to-End Processing Flow

Webhook processing must follow a deterministic sequence of operations, from reception to acknowledgement.

Each step in this flow must be executed in a controlled and failure-aware manner. Partial execution or skipping validation steps may lead to inconsistent transaction state or incorrect processing outcomes.

Webhook Reception and Validation

Webhook notifications are delivered via an HTTP POST request to the merchant endpoint.

At reception time, the following validations must be performed:

• HTTP method must be POST
• Content-Type must be application/json
• Request body must be present and non-empty
• Required headers must be present:
  • X-Initialization-Vector
  • X-Authentication-Tag

These validations ensure that only structurally valid and processable requests are accepted into the processing pipeline.

Header semantics, transport guarantees, and authenticity requirements are defined in the E.1 Webhooks (Notifications) section.

Payload Decoding and Decryption

The webhook payload is received as a Base64-encoded encrypted message and must be transformed into a usable JSON structure through a two-step process:

1. Base64 decoding of the request body
2. Decryption using AES in GCM mode

The decryption process requires:

• Secret key (provisioned configuration)
• Initialization Vector (from header X-Initialization-Vector)
• Authentication Tag (from header X-Authentication-Tag)

The result of this process must be a valid UTF-8 JSON payload. Any failure during decoding or decryption must be treated as a non-processable notification.

The encryption model and required parameters are defined in the E.1 Webhooks (Notifications) section.

Example Processing Pipeline

The following pseudo-implementation illustrates the minimum safe processing model:

Receive HTTP POST /webhook

Validate:
  - Headers present
  - Body not empty

Extract:
  - iv = Base64Decode(X-Initialization-Vector)
  - tag = Base64Decode(X-Authentication-Tag)
  - payload = Base64Decode(request.body)

Decrypt:
  json = AES_GCM_Decrypt(payload, key, iv, tag)

Parse:
  data = JSON.parse(json)

Process:
  transactionID = data.transactionID
  notificationID = data.notificationID

  if alreadyProcessed(notificationID):
      return HTTP 200  

  handleBusinessLogic(data)
  persist(data)

Respond:
  return HTTP 200 with acknowledgement

This model ensures that webhook handling remains deterministic, idempotent, and safe under repeated delivery.

Transaction Correlation and Idempotent Processing

After decryption, the payload must be correlated with the internal transaction model.

The following fields are critical:

• transactionID → primary transaction identifier
• notificationID → unique identifier for the webhook event

Processing must enforce:

• Idempotency using notificationID
• Safe reprocessing without side effects
• No assumptions regarding delivery order
• Consistent transaction state transitions

These principles align with the idempotency and consistency requirements defined in F.6 Production Readiness Guidelines.

Processing Model and Execution Architecture

Webhook processing must be designed to avoid blocking and to ensure resilience under load and failure conditions.

Recommended approach:

• Perform minimal validation synchronously
• Acknowledge the webhook immediately
• Process the payload asynchronously

This ensures:

• Fast acknowledgement to SPG
• Reduced risk of retries
• Improved system resilience and scalability

Acknowledgement Handling

After successful reception and validation, the system must return the following response:

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

Requirements:

• HTTP status must be 200
• notificationID must match the received value
• Response must be returned immediately
• No business logic must block the response

Failure to acknowledge correctly may result in repeated delivery attempts.

Integration with Transaction State Validation

Webhook notifications must not be treated as the authoritative source of transaction state.

After processing the notification:

• Extract transactionID
• Call: GET <ROOT_URL>/api/v2/payments/{transactionID}/status
• Validate the resulting state

This ensures consistency between:

• event-driven updates (webhooks)
• authoritative state (Status API)

This model aligns with the transaction consistency principles defined in F.3 Success and Error Scenarios.

Failure Handling

The processing pipeline must explicitly handle failure scenarios:

• Missing or invalid headers → reject or log
• Base64 decoding failure → discard
• Decryption failure → discard
• Invalid JSON → discard
• Duplicate notification → ignore safely
• Processing failure → trigger controlled internal retry mechanisms

Under no circumstance should failures result in:

• partial state updates
• duplicated processing
• inconsistent transaction state

Final Consideration

Webhook reception and processing is a security-sensitive and correctness-critical component of SPG integrations.

A correct implementation requires:

• strict validation of incoming requests
• secure and accurate decryption
• idempotent and resilient processing
• proper acknowledgement handling
• integration with authoritative state validation

By implementing the processing model described in this section, integrators ensure that webhook handling is secure, reliable, and fully aligned with the SPG asynchronous execution model, maintaining consistency and correctness across all transaction scenarios.