Overview

SIBS Payment Gateway (SPG) webhooks must be configured in the SPG Backoffice to enable asynchronous notifications for transaction events.

This page provides a step-by-step guide to:

• Configure webhook endpoints
• Define scope and event types
• Retrieve and manage the webhook secret
• Test and validate webhook delivery

This configuration is required for the webhook processing model described in:

• E.1.4 Receiving and Processing Webhooks
• E.1.5 Security and Validation
• E.1.8 Webhooks vs Status API (Consistency Model)

Prerequisites

Before configuring webhooks, ensure that:

• A public HTTPS endpoint is available
• The endpoint supports TLS 1.2 or higher
• The endpoint is reachable from the internet
• The endpoint:
  • Accepts HTTP POST requests
  • Returns HTTP 200 OK quickly with the expected acknowledgement response body
  • Supports encrypted payload processing

Webhook processing must be asynchronous. Do not perform heavy logic before returning HTTP 200.

See E.1.4 Receiving and Processing Webhooks.

Step-by-Step Configuration

Step 1 – Access SIBS SPG Backoffice

• Log in to the SIBS SPG Backoffice

Step 2 – Navigate to SPG Module

• In the left menu, select:

SIBS Payment Gateway 2.0

If this menu is not visible, contact the SIBS onboarding team. Required permissions or configuration may be missing.

Step 3 – Open Webhooks Section

• Navigate to:

Webhooks

Step 4 – Create New Webhook

• Click:

Add new webhook

Step 5 – Select Webhook Type

Choose between:

URL (Recommended)

• Select URL
• Provide your endpoint:

https://www.merchant.com/sibswebhookendpoint

Requirements:

• Publicly accessible
• HTTPS (TLS 1.2+)
• Responds quickly with HTTP 200 OK and the expected acknowledgement response body

E-mail (Alternative)

• Allows receiving notifications via email
• Suitable only for manual or fallback scenarios

Best Practice
Always use URL-based webhooks for system integrations.

Step 6 – Define Scope and Events

Scope

• Merchant
• Store
• Terminal

Recommended:

Merchant

Ensures full coverage of all transactions for the merchant.

Notification Types

Select relevant event types:

• MB WAY
• MB Reference
• Key Enter / Token
• QR Code / QR Code Express
• Authorised Payment
• XPAY

Select all applicable payment methods used in your integration.

Step 7 – Retrieve and Store Secret

• A Base64 secret is generated

This secret is required for:

• Payload decryption
• Integrity validation

Critical Requirements

• Store securely (e.g., Key Vault)
• Never expose in logs
• Do not share

This secret is required for implementation in
E.1.5 Security and Validation

Step 8 – Configure Notification Email

• Provide an email to receive:
  • Delivery failures
  • Webhook system errors

Step 9 – Create Webhook

• Click:

Create Webhook

Step 10 – Webhook Created

• The webhook appears in the list
• A confirmation message is displayed

Webhook Testing

Step 11 – Open Test Option

• On the created / selected webhook click:

Actions → Test

Step 12 – Execute Test

• Click:

Test

Validate:

• Notification sent
• Response received
• Parsed payload

If the test fails, validate:

• Endpoint availability
• HTTP response (must be HTTP 200 OK with valid acknowledgement response body)
• Decryption logic (see E.1.5 Security and Validation)

Expected Outcome

A successful test confirms:

• Endpoint is reachable
• HTTP response is HTTP 200 OK with valid acknowledgement response body
• Integration is operational

Common Issues

Endpoint Not Reachable

• Invalid URL
• Firewall blocking requests
• DNS issues

Invalid Webhook acknowledgement (non-200 or invalid response body)

• Endpoint does not return HTTP 200 OK
• Missing or invalid acknowledgement response body
• Processing too slow before acknowledgement
• Errors in endpoint logic

Decryption Errors

• Wrong secret
• Incorrect AES-GCM implementation

See E.1.5 Security and Validation for implementation details

Best Practices

• Use URL webhooks (not email)
• Configure at merchant level
• Store secret securely
• Always test after configuration
• Monitor webhook delivery (see E.1.6 Logging and Monitoring)

Relationship with Webhook Processing

Once configured:

1. SIBS sends webhook notifications
2. Merchant receives and acknowledges
3. Payload is decrypted and validated
4. Processing is performed asynchronously
5. Final state is confirmed via Status API

See:

• E.1.4 Receiving and Processing Webhooks
• E.1.5 Security and Validation
• E.1.8 Webhooks vs Status API (Consistency Model)

Summary

Webhook configuration in the SPG Backoffice is the entry point for asynchronous transaction processing.

A correct setup ensures:

• Reliable event delivery
• Secure communication
• Proper integration with backend systems