Webhooks API

Overview
API Endpoint
API Philosophy
How Webhooks Work
Why Webhooks Are Required
Webhook Events
Authentication
Webhook Payload Security
Encryption Details
Webhook Management
Webhook Status
Testing Webhooks
Integration Checklist
Use Cases
Best Practices
Next Steps

Overview

Webhooks allow Modulus Labs to notify your application in real-time when QR Ph transactions are completed. Instead of repeatedly polling the API to check transaction status, webhooks push updates directly to your server the moment an event occurs.

Webhooks are REQUIRED for QR Ph integration. Without webhooks, you cannot receive transaction status updates, which poses significant security risks. Your system would be unable to verify if a customer’s payment succeeded or failed.

Setup Guide

Configure webhook endpoints for your account

API Reference

Complete webhook management API documentation

Receiving Webhooks

Handle and process webhook notifications

Payload Structure

Understand webhook payload format and encryption

API Endpoint

All Webhook API requests should be made to the sandbox environment:

https://webhooks.sbx.moduluslabs.io

This is the sandbox environment URL. Production credentials and URL will be provided separately when you’re ready to go live.

API Philosophy

The Webhooks API is designed for reliability and security:

REST Architecture

Standard REST API with predictable URLs and HTTP methods

JSON Format

All requests and responses use JSON

HTTPS Only

All API requests must be made over HTTPS

HTTP Basic Auth

Simple authentication using your Secret Key

JWE Encryption

All webhook payloads encrypted with JWE for security

Automatic Retries

Up to 4 delivery attempts with 15-minute intervals

PCI DSS 4.1 Certified

Modulus Labs is PCI DSS 4.1 compliant, ensuring the highest standards of payment security and data protection

How Webhooks Work

Configure Webhook Endpoint

Create a webhook endpoint on your server that accepts POST requests and register it with Modulus Labs using the Webhook API.

Customer Completes Payment

When a customer scans your Dynamic QR Ph code and completes payment in their banking app, the payment network processes the transaction.

Modulus Labs Sends Notification

Modulus Labs immediately sends a POST request to your webhook endpoint with the encrypted transaction details.

Your Server Processes Webhook

Your server receives the webhook, verifies its authenticity, decrypts the payload, and updates the order status in your system.

Automatic Retries

If your server doesn’t respond successfully, Modulus Labs automatically retries up to 3 more times at 15-minute intervals.

Why Webhooks Are Required

Can I skip webhooks and just poll the API?

No. Webhooks are mandatory for QR Ph integration. Polling is inefficient, introduces delays, and creates security gaps where fraudulent transactions could go undetected.Without webhooks:

You won’t know when payments succeed or fail
Customers may complete payment but never receive their order
Your system cannot verify transaction authenticity
You risk order fulfillment errors and revenue loss

Real-Time Order Fulfillment

Webhooks notify you instantly when payment completes, enabling immediate order fulfillment. Customers receive their digital goods, confirmations, or service access without delay.

Security and Fraud Prevention

Every webhook is encrypted with JWE (JSON Web Encryption). You can verify that notifications genuinely came from Modulus Labs and haven’t been tampered with, preventing fraudulent payment claims.

Reliability with Automatic Retries

If your server is temporarily unavailable, Modulus Labs automatically retries webhook delivery up to 4 times:

Immediately upon transaction completion
After 15 minutes (retry 1)
After 30 minutes (retry 2)
After 45 minutes (retry 3)

This ensures you receive critical payment notifications even during brief outages.

Multi-Merchant Support

If you manage multiple merchants, use the activation-code header to identify which merchant account the webhook belongs to, enabling centralized webhook handling.

Webhook Events

Modulus Labs sends webhooks for these QR Ph transaction events:

Event	Description	When It’s Sent
`QRPH_SUCCESS`	Payment completed successfully	Customer’s bank confirms payment and transfers funds
`QRPH_DECLINED`	Payment failed or was declined	Bank rejects payment due to insufficient funds, limits, or other issues

Both success and declined webhooks are critical. Handle declined payments gracefully by notifying customers and offering alternative payment methods.

Authentication

The Webhook API uses HTTP Basic Authentication, identical to the QR API.

Use Your Secret Key

Your secret key serves as the username. Leave the password empty.

Format the Authorization Header

Authorization: Basic {base64(secret_key:)}

Note the colon (:) after your secret key before base64 encoding.

Send with Every Request

Include the Authorization header in all Webhook API requests (creating, updating, deleting webhooks).

Authentication Guide

Detailed authentication instructions and code examples

Webhook Payload Security

All webhook payloads are encrypted using JWE (JSON Web Encryption) to protect sensitive transaction data.

Encryption Details

Content Encryption Algorithm: A256CBC-HS512 (AES-256-CBC with HMAC SHA-512)
Key Encryption Algorithm: A256KW (AES-256 Key Wrap)
Format: JSON Web Encryption Compact Serialization

{
  "data": "eyJhbGciOiJBMjU2S1ciLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIn0.9x4mZBJaKc7QPZ-5u8NOBzjK-cQ2puX9eBaWOWgpGJ6SRvb8P8O2xA.Yp8AbjvIrVH46GKQtLV9PA.zlDcH_ES9xg7OdstFYn..."
}

Payload Structure

Complete payload documentation with decryption examples

Webhook Management

The Webhook API provides full CRUD (Create, Read, Update, Delete) operations for managing webhook endpoints.

Create Webhook

List Webhooks

View all configured webhooks

Update Webhook

Modify webhook URL or actions

Delete Webhook

Remove a webhook endpoint

Webhook Status

Each webhook can have one of two statuses:

Status	Description
`ENABLED`	Webhook is active and will receive notifications
`DISABLED`	Webhook is paused and will not receive notifications (useful for maintenance)

Disable webhooks temporarily during server maintenance instead of deleting them. This preserves your configuration and makes it easy to resume receiving notifications.

Testing Webhooks

The Webhook API includes a Simulate endpoint for testing your webhook integration in the sandbox environment without generating real transactions.

Use the Create Webhook API to register your test endpoint

Call the Simulate API

Trigger a test webhook with SUCCESS or DECLINED status

Verify Your Handler

Confirm your server correctly receives, decrypts, and processes the webhook

Test Error Scenarios

Simulate declined payments to ensure proper error handling

Simulate Webhook

Test your webhook integration without real transactions

Integration Checklist

Use this checklist to ensure your webhook integration is complete:

Use Cases

E-commerce Order Fulfillment

Customer completes QR Ph payment at checkout. Webhook notifies your system instantly, triggering order processing, inventory updates, and shipping label generation.

Point of Sale (POS)

In-store customer scans QR code and pays. Webhook notifies POS system to print receipt and complete transaction without manual verification.

Digital Content Delivery

Customer purchases downloadable content. Webhook triggers instant delivery of download link or license key upon payment confirmation.

Best Practices

Idempotency

Design webhook handlers to be idempotent. You may receive the same webhook multiple times due to retries, so use referenceNumber to prevent duplicate processing.

Fast Response

Return 200 OK quickly (within 10 seconds). Process webhooks asynchronously using background jobs to avoid timeouts.

Security First

Always decrypt and verify webhook payloads. Never trust webhook data without cryptographic verification.

Logging

Log every webhook receipt with timestamp, referenceNumber, and processing result for debugging and audit trails.

Error Monitoring

Set up alerts for webhook processing failures. Missing webhook notifications means missed payments.

Graceful Degradation

If webhook processing fails, have a fallback mechanism to detect and recover from missed notifications.

Next Steps

Setup Guide

Configure your first webhook endpoint

Receiving Webhooks

Implement webhook handling in your application

Payload Documentation

Understand webhook payload structure and decryption

Create Webhook API

Ready to integrate webhooks? Start with the Setup Guide to register your first webhook endpoint.

Enums Reference Webhook Setup

⌘I

QR API

Onboarding API

Shared Resources

​Overview

Setup Guide

API Reference

Receiving Webhooks

Payload Structure

​API Endpoint

​API Philosophy

REST Architecture

JSON Format

HTTPS Only

HTTP Basic Auth

JWE Encryption

Automatic Retries

PCI DSS 4.1 Certified

​How Webhooks Work

​Why Webhooks Are Required

​Webhook Events

​Authentication

Authentication Guide

​Webhook Payload Security

​Encryption Details

Payload Structure

​Webhook Management

Create Webhook

List Webhooks

Update Webhook

Delete Webhook

​Webhook Status

​Testing Webhooks

Simulate Webhook

​Integration Checklist

​Use Cases

​Best Practices

Idempotency

Fast Response

Security First

Logging

Error Monitoring

Graceful Degradation

​Next Steps

Setup Guide

Receiving Webhooks

Payload Documentation

Create Webhook API

Overview

API Endpoint

API Philosophy

How Webhooks Work

Why Webhooks Are Required

Webhook Events

Authentication

Webhook Payload Security

Encryption Details

Webhook Management

Webhook Status

Testing Webhooks

Integration Checklist

Use Cases

Best Practices

Next Steps