Create Webhook - Modulus Labs API

# Note: You need to encrypt the payload first using a script/tool
# See the Encryption Guide for JWE token creation

# 1. Create encrypted JWE token (using external tool/script)
ENCRYPTED_TOKEN="eyJhbGciOiJBMjU2S1ciL..."

# 2. Make API request
curl -X POST https://webhooks.sbx.moduluslabs.io/v1/webhooks \
  -u sk_your_secret_key: \
  -H "Content-Type: application/json" \
  -d "{\"request\": {\"Token\": \"$ENCRYPTED_TOKEN\"}}"

# 3. Response contains the created webhook object

{
  "id": "a78efd32-de3b-4854-b599-11ae9f98f97e",
  "webhookAction": "QRPH_SUCCESS",
  "webhookStatus": "ENABLED",
  "callbackUrl": "https://api.yourcompany.com/webhooks/success"
}

POST

webhooks

# Note: You need to encrypt the payload first using a script/tool
# See the Encryption Guide for JWE token creation

# 1. Create encrypted JWE token (using external tool/script)
ENCRYPTED_TOKEN="eyJhbGciOiJBMjU2S1ciL..."

# 2. Make API request
curl -X POST https://webhooks.sbx.moduluslabs.io/v1/webhooks \
  -u sk_your_secret_key: \
  -H "Content-Type: application/json" \
  -d "{\"request\": {\"Token\": \"$ENCRYPTED_TOKEN\"}}"

# 3. Response contains the created webhook object

{
  "id": "a78efd32-de3b-4854-b599-11ae9f98f97e",
  "webhookAction": "QRPH_SUCCESS",
  "webhookStatus": "ENABLED",
  "callbackUrl": "https://api.yourcompany.com/webhooks/success"
}

Overview

The Create Webhook endpoint allows you to register a new webhook URL that will receive real-time notifications when QR Ph transactions complete. You can specify which transaction events (success or declined) to receive and enable or disable the webhook immediately.

Webhooks are required for QR Ph integration. Without a registered webhook, you cannot receive transaction status updates, which poses significant security risks.

Endpoint

POST https://webhooks.sbx.moduluslabs.io/v1/webhooks

Authentication

This endpoint requires HTTP Basic Authentication using your Secret Key.

Authorization: Basic {base64(secret_key:)}

Request

Headers

Header	Value	Required	Description
`Authorization`	`Basic {base64(secret_key:)}`	Yes	HTTP Basic Auth with your secret key
`Content-Type`	`application/json`	Yes	Request body format
`activation-code`	string	No	Merchant activation code for multi-merchant setups

activation-code

string

Optional activation code to identify which merchant this webhook belongs to. Used for multi-merchant environments where a single platform manages webhooks for multiple merchants.Example: "MERCHANT_ABC_123"When you create a webhook with an activation code, Modulus Labs includes the same activation-code in the header of webhook notifications sent to your endpoint.

Prerequisites

Before creating a webhook, ensure you have:

Your Secret Key for HTTP Basic Authentication

See the Encryption Guide to understand how JWE tokens work — you’ll need this to decrypt incoming webhook notifications sent to your endpoint.

Encrypted Payload Structure

The request body must contain a request object with a JWE-encrypted Token that includes your webhook configuration:

{
  "request": {
    "Token": "eyJhbGciOiJBMjU2S1ciLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIn0..."
  }
}

Body Parameters (Encrypted Payload)

The following parameters describe the payload that must be JWE-encrypted into the Token field. See the Encryption Guide for details on creating JWE tokens.

Field	Type	Required	Description
`callbackUrl`	string	Yes	HTTPS URL where Modulus Labs sends webhook notifications
`webhookAction`	string	Yes	Transaction events to receive: `QRPH_SUCCESS`, `QRPH_DECLINED`

callbackUrl

The HTTPS URL where Modulus Labs sends webhook notifications. Must be publicly accessible and use HTTPS.

Format: Valid HTTPS URL
Example: "https://api.yourcompany.com/webhooks/modulus"

Requirements:

Must use HTTPS protocol (HTTP not supported in production)
Must be publicly accessible from the internet
Must respond within 10 seconds
Should return 200 OK to acknowledge receipt

webhookAction

Transaction events you want to receive notifications for. Include one or both values:

QRPH_SUCCESS - Receive notifications when payments succeed
QRPH_DECLINED - Receive notifications when payments are declined

Example: "QRPH_SUCCESS"

We recommend including both actions. Handling declined payments allows you to provide better customer support and offer alternative payment methods.

Example Payload (Before Encryption)

{
  "webhookAction": "QRPH_SUCCESS",
  "callbackUrl": "https://api.yourcompany.com/webhooks/success"
}

Response

Success Response

Status Code: 201 Created Returns the created webhook object with a unique id that you can use to update or delete the webhook later.

integer

Unique identifier for the webhook. Save this value - you’ll need it to update or delete the webhook.Example: a78efd32-de3b-4854-b599-11ae9f98f97e

webhookAction

string

String of webhook actions this endpoint will receive.Example: "QRPH_SUCCESS" "QRPH_DECLINED"

webhookStatus

string

Current webhook status: ENABLED or DISABLEDExample: "ENABLED"

callbackUrl

string

The webhook URL you registered.Example: "https://api.yourcompany.com/webhooks/modulus"

Response Example

{
  "id": "a78efd32-de3b-4854-b599-11ae9f98f97e",
  "webhookAction": "QRPH_SUCCESS",
  "webhookStatus": "ENABLED",
  "callbackUrl": "https://api.yourcompany.com/webhooks/success"
}

{
  "id": "a78efd32-de3b-4854-b599-11ae9f98f97e",
  "webhookAction": "QRPH_SUCCESS",
  "webhookStatus": "ENABLED",
  "callbackUrl": "https://api.yourcompany.com/webhooks/success"
}

Save the webhook ID! You’ll need the id value to update or delete this webhook using the Update or Delete endpoints.

Error Responses

400 Bad Request

Status Code: 400Causes:

Invalid webhook URL format
Missing required fields
Invalid action values
Invalid status value

Response Example:

{
  "code": "20000002",
  "error": "Invalid callbackUrl: must be a valid HTTPS URL",
  "referenceNumber": "abc123-def456-ghi789"
}

Solutions:

Ensure callbackUrl uses HTTPS protocol
Verify all required fields are present
Check that actions contain valid values (QRPH_SUCCESS, QRPH_DECLINED)
Ensure status is either ENABLED or DISABLED

401 Unauthorized

Status Code: 401Cause: Invalid or missing authentication credentialsSolution:

Verify your secret key is correct
Ensure Authorization header format: Basic {base64(secret_key:)}
Check you’re using the right environment (sandbox vs production)

409 Conflict

Status Code: 409Cause: Webhook URL already registered for this merchantResponse Example:

{
  "code": "20000003",
  "error": "Webhook URL already exists",
  "referenceNumber": "abc123-def456-ghi789"
}

Solution:

Use a different webhook URL, or
Update the existing webhook using Update Webhook API, or
Delete the existing webhook and create a new one

500 Internal Server Error

Status Code: 500Cause: Unexpected server errorSolution:

Retry the request
If the issue persists, contact Modulus Labs support with the reference number

# Note: You need to encrypt the payload first using a script/tool
# See the Encryption Guide for JWE token creation

# 1. Create encrypted JWE token (using external tool/script)
ENCRYPTED_TOKEN="eyJhbGciOiJBMjU2S1ciL..."

# 2. Make API request
curl -X POST https://webhooks.sbx.moduluslabs.io/v1/webhooks \
  -u sk_your_secret_key: \
  -H "Content-Type: application/json" \
  -d "{\"request\": {\"Token\": \"$ENCRYPTED_TOKEN\"}}"

# 3. Response contains the created webhook object

Multi-Merchant Setup

If you manage multiple merchants, use the activation-code header to associate the webhook with a specific merchant:

# Encrypt your payload into a JWE token first
ENCRYPTED_TOKEN="eyJhbGciOiJBMjU2S1ciL..."

curl -X POST https://webhooks.sbx.moduluslabs.io/v1/webhooks \
  -u sk_your_secret_key: \
  -H "Content-Type: application/json" \
  -H "activation-code: MERCHANT_ABC_123" \
  -d "{\"request\": {\"Token\": \"$ENCRYPTED_TOKEN\"}}"

When Modulus Labs sends webhook notifications for this merchant, the activation-code header will be included in the request:

app.post('/webhooks/modulus', (req, res) => {
  const activationCode = req.headers['activation-code'];
  // "MERCHANT_ABC_123"

  // Route to appropriate merchant handler
  const merchant = getMerchantByActivationCode(activationCode);
  processWebhook(merchant, req.body);
});

Use Cases

E-commerce Integration

const webhook = await createWebhook({
  callbackUrl: 'https://shop.example.com/api/payments/webhook',
  webhookAction: 'QRPH_SUCCESS',
  status: 'ENABLED'
});

// Webhook will notify you instantly when customers complete QR Ph payments

POS System

const webhook = await createWebhook({
  callbackUrl: 'https://pos.example.com/webhooks/payment',
  webhookAction: ['QRPH_SUCCESS'],  // Only success events for POS
  status: 'ENABLED'
});

Development and Testing

Create a disabled webhook during development, enable it when ready:

// Create disabled webhook for testing
const webhook = await createWebhook({
  callbackUrl: 'https://dev.example.com/webhooks/test',
  webhookAction: 'QRPH_SUCCESS',
  status: 'DISABLED'  // Won't receive notifications yet
});

// Enable later using Update Webhook API
await updateWebhook(webhook.id, { status: 'ENABLED' });

Best Practices

Use HTTPS Only

Always use HTTPS URLs for webhooks. HTTP is insecure and not supported in production.

Save Webhook ID

Store the returned id in your database. You’ll need it to update or delete the webhook.

Test Before Enabling

Create webhooks with DISABLED status during development. Test with the Simulate API before enabling.

Include Both Actions

Unique URLs per Environment

Use different webhook URLs for sandbox and production to avoid mixing test and live data.

Verify Connectivity First

Test your webhook endpoint is accessible before registering it with the API.

Validation Checklist

Before creating a webhook, verify:

What Happens Next?

After creating a webhook:

Webhook is Registered

Modulus Labs saves your webhook configuration and begins monitoring for transaction events.

Transactions Trigger Notifications

When QR Ph transactions complete, Modulus Labs sends encrypted webhook notifications to your URL.

Automatic Retries

If your endpoint doesn’t respond with 200 OK, Modulus Labs automatically retries up to 3 more times at 15-minute intervals.

You Process Webhooks

Your endpoint decrypts payloads, updates order status, and fulfills transactions in real-time.

Next Steps

Test Your Webhook

Use the Simulate API to send test webhooks

View Webhooks

Get all registered webhooks for your account

Update Webhook

Modify webhook URL, webhook Action, or status

Receiving Webhooks

Learn how to process webhook notifications

Authorizations

Authorization

string

header

required

HTTP Basic Authentication using your Secret Key as the username and an empty password

Headers

activation-code

string

Optional activation code to identify which merchant this webhook belongs to. Used for multi-merchant environments.

Body

application/json

request

object

required

Show child attributes

Response

Webhook created successfully

string

Unique identifier for the webhook

webhookAction

enum<string>[]

List of transaction events this webhook receives

Available options:

QRPH_SUCCESS,

QRPH_DECLINED

webhookStatus

enum<string>

Current status of the webhook

Available options:

ENABLED,

DISABLED

webhookUrl

string<uri>

The HTTPS URL where notifications are sent

Ping Get Webhooks

⌘I

​Overview

​Endpoint

​Authentication

​Request

​Headers

​Prerequisites

​Encrypted Payload Structure

​Body Parameters (Encrypted Payload)

​Example Payload (Before Encryption)

​Response

​Success Response

​Response Example

​Error Responses

​Multi-Merchant Setup

​Use Cases

​Best Practices

Use HTTPS Only

Save Webhook ID

Test Before Enabling

Include Both Actions

Unique URLs per Environment

Verify Connectivity First

​Validation Checklist

​What Happens Next?

​Next Steps

Test Your Webhook

View Webhooks

Update Webhook

Receiving Webhooks

Authorizations

Headers

Body

Response

Overview

Endpoint

Authentication

Request

Headers

Prerequisites

Encrypted Payload Structure

Body Parameters (Encrypted Payload)

Example Payload (Before Encryption)

Response

Success Response

Response Example

Error Responses

Multi-Merchant Setup

Use Cases

Best Practices

Validation Checklist

What Happens Next?

Next Steps