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

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
  • merchantTransactionId
• Processing outcome (success / failure)

5. Status API Interaction

Log all interactions with the Status API:

• Request timestamp
• Endpoint called
• Response received
• Final 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

• merchantTransactionId
• Internal event ID (if applicable)

Recommended Approach

Monitoring Strategy

Monitoring must cover both technical and business-level indicators.

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 API results
• Transactions without final state confirmation
• Delayed status resolution

4. Error Monitoring

Track:

• Decryption failures
• Validation failures
• Status API 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 API failures

Reconciliation

Due to the asynchronous nature of webhooks, periodic reconciliation is required.

Recommended Approach

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

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)
• 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 final state using the Status API
• Lack of alerting for critical failures

Summary

Logging and monitoring are essential components of SPG webhook integrations.

A robust implementation must provide:

• Full 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.