Overview

Webhook-based integrations with SIBS Payment Gateway (SPG) rely on asynchronous event delivery and external system communication. As a result, logging and monitoring are critical to ensure visibility, traceability, and operational reliability.

A production-ready implementation must provide full observability across the webhook lifecycle, from reception to final business processing, including interactions with the Status Inquiry.

Objectives

The logging and monitoring strategy must enable:

• End-to-end transaction traceability
• Detection of failed or delayed processing
• Diagnosis of integration issues
• Recovery from missed or inconsistent events
• Operational visibility in asynchronous flows

Observability Flow

Logging Strategy

Logging must be implemented at all stages of the webhook lifecycle.

1. Webhook Reception

Log the following:

• Timestamp of reception
• Raw request body (encrypted payload)
• Relevant HTTP headers:
  • X-Initialization-Vector
  • X-Authentication-Tag
• Request metadata (IP, endpoint, response time)

2. Decryption and Validation

Log:

• Decryption success or failure
• Validation result (valid / invalid payload)
• Errors during decryption (without exposing sensitive data)

3. Event Persistence / Enqueue

Log:

• Event storage or queue insertion result
• Internal event identifier (if applicable)
• Correlation with transaction identifiers

4. Asynchronous Processing

Log:

• Processing start and completion timestamps
• Extracted identifiers:
  • transactionID
  • merchant.transactionId (merchantTransactionId)
• Processing outcome (success / failure)

5. Status Inquiry Interaction

Log all interactions with the Status Inquiry:

• Request timestamp
• Endpoint called
• Response received
• Transaction state returned

Correlation and Traceability

To ensure end-to-end visibility, logs must be correlated using consistent identifiers.

Primary Correlation Key

• transactionID

Secondary Correlation Keys

• merchant.transactionId (merchantTransactionId)
• Internal event ID (if applicable)

Recommended Approach

Monitoring Strategy

Monitoring must cover both technical and business-level indicators.

Webhook delivery visibility, retry analysis, operational metrics, and monitoring capabilities are further described in E.1.9 – Webhook Operational Statistics and Monitoring.

1. Webhook Delivery Monitoring

Track:

• Number of webhooks received
• Response time of webhook endpoint
• Rate of webhook acknowledgements not complying with the expected contract (HTTP 200 OK with valid acknowledgement response body)

2. Processing Monitoring

Track:

• Queue size / backlog
• Processing latency
• Failed processing attempts

3. Status Consistency Monitoring

Track:

• Differences between webhook events and Status Inquiry results
• Transactions without final state confirmation
• Delayed status resolution

4. Error Monitoring

Track:

• Decryption failures
• Validation failures
• Status Inquiry errors
• Internal processing errors

Alerting

Alerts must be configured for critical conditions.

Recommended Alerts

• High rate of webhook failures
• Decryption failure spikes
• Processing backlog growth
• Missing transaction finalization
• Status Inquiry failures

Reconciliation

Due to the asynchronous nature of webhooks, periodic reconciliation should be implemented where operational confirmation, recovery, or inconsistency detection is required.

Recommended Approach

• Periodically query transactions using the Status Inquiry APIs
• Compare internal state with SPG state
• Detect and correct inconsistencies

Detailed reconciliation strategies and operational recovery patterns are described in E.2.7 – Reconciliation Patterns.

Observability Architecture

A typical enterprise setup includes:

• Centralized logging system
• Metrics and monitoring platform
• Alerting system
• Dashboards for real-time visibility

Best Practices

• Log all stages of the webhook lifecycle
• Use structured logging (JSON recommended)
• Retain logs according to operational, compliance, audit, and troubleshooting requirements applicable to the target environment.
• Always include correlation identifiers
• Avoid logging sensitive data in plain text
• Monitor both technical and business metrics
• Combine webhook-driven processing with reconciliation

Common Pitfalls

• Not logging webhook payloads
• Missing correlation between systems
• Ignoring failed processing events
• Not monitoring asynchronous delays
• Not validating transaction state using Status Inquiry when additional confirmation, recovery, reconciliation, or inconsistency resolution is required
• Lack of alerting for critical failures

Summary

Logging and monitoring are essential components of SPG webhook integrations.

A robust implementation must provide:

• End-to-end transaction traceability
• Visibility into asynchronous processing
• Detection and alerting of failures
• Support for reconciliation and recovery

This ensures a reliable, observable, and production-ready integration aligned with enterprise standards.