Simulate 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 containing the simulate payload
ENCRYPTED_TOKEN="eyJhbGciOiJBMjU2S1ciL..."

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

{
"id": "a78efd32-de3b-4854-b599-11ae9f98f97e"
}

POST

webhooks

qrph

simulate

# 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 containing the simulate payload
ENCRYPTED_TOKEN="eyJhbGciOiJBMjU2S1ciL..."

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

{
"id": "a78efd32-de3b-4854-b599-11ae9f98f97e"
}

Overview

The Simulate Webhook endpoint allows you to test your webhook integration without creating real QR codes or processing actual transactions. It sends encrypted webhook notifications to your registered endpoint, just like real transaction webhooks.

Sandbox Only: This endpoint is only available in the sandbox environment for testing purposes. It’s not available in production.

The simulated webhook payloads sent to your endpoint are JWE-encrypted, identical to real transaction webhooks. See the Encryption Guide to understand how to decrypt incoming notifications.

Endpoint

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

Authentication

This endpoint requires HTTP Basic Authentication using your Secret Key.

Authorization: Basic {base64(secret_key:)}

Request

Headers

Header	Value	Required
`Authorization`	`Basic {base64(secret_key:)}`	Yes
`Content-Type`	`application/json`	Yes

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
`qrBody`	string	Yes	Raw QRPH payload used to simulate a transaction
`useCase`	string	Yes	Transaction event type: `SUCCESS`, `MISSING_DESTINATION_ACCOUNT`, `MISSING_PARTNER_REVENUE_ACCOUNT`, or `UNSUPPORTED_TRANSFER_TYPE`

qrBody

The raw QRPH payload used to simulate a transaction.

Example: "00020101021228820011ph.ppmi.p2m0111CUOBPHM2XXX03258eff02de-e172-4b0d-bc5b-3041288500100000705033015204601653036085406100.005802PH5912MAIN ACCOUNT6006MANILA630412C0"

useCase

The type of transaction event to simulate:

SUCCESS - Simulates a successful payment
MISSING_DESTINATION_ACCOUNT - Simulates a declined payment (missing destination account)
MISSING_PARTNER_REVENUE_ACCOUNT - Simulates a declined payment (missing partner revenue account)
UNSUPPORTED_TRANSFER_TYPE - Simulates a declined payment (unsupported transfer type)

Example: "SUCCESS"

Example Payloads (Before Encryption)

{
  "qrBody":
    "00020101021228820011ph.ppmi.p2m0111CUOBPHM2XXX03258eff02de-e172-4b0d-bc5b-3041288500100000705033015204601653036085406100.005802PH5912MAIN ACCOUNT6006MANILA630412C0",
  "useCase": "SUCCESS"
}

Response

Success Response

Status Code: 200 OK Returns confirmation that the simulated webhook was sent to your registered endpoint.

string

The unique identifier of the original transaction (i.e., the id returned from the Create Dynamic QR Ph response).Example: "a78efd32-de3b-4854-b599-11ae9f98f97e"

Response Example

{
"id": "a78efd32-de3b-4854-b599-11ae9f98f97e"
}

{
"id": "a78efd32-de3b-4854-b599-11ae9f98f97e"
}

Error Responses

400 Bad Request

Status Code: 400Causes:

Missing useCase field
Invalid useCase value

Response Example:

{
  "code": "20000003",
  "error": "useCase is invalid.",
  "referenceNumber": "abc123-def456-ghi789"
}

Solution:

Ensure useCase is one of: SUCCESS, MISSING_DESTINATION_ACCOUNT, MISSING_PARTNER_REVENUE_ACCOUNT, or UNSUPPORTED_TRANSFER_TYPE
Check spelling and capitalization

401 Unauthorized

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

Verify your secret key is correct
Ensure Authorization header format: Basic {base64(secret_key:)}

404 Not Found

Status Code: 404Cause: No enabled webhooks configuredResponse Example:

{
  "code": "20000005",
  "error": "No enabled webhooks found",
  "referenceNumber": "abc123-def456-ghi789"
}

Solution:

Create at least one webhook using Create Webhook API
Ensure webhook status is ENABLED
Verify webhook actions include the simulated event type

500 Internal Server Error

Status Code: 500Cause: Unexpected server errorSolution:

Retry the request
If the issue persists, contact Modulus Labs support

# 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 containing the simulate payload
ENCRYPTED_TOKEN="eyJhbGciOiJBMjU2S1ciL..."

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

Testing Workflow

Create a webhook endpoint pointing to your test server:

const webhook = await createWebhook(
  'https://your-test-server.com/webhooks/modulus',
  ['QRPH_SUCCESS', 'QRPH_DECLINED'],
  'ENABLED'
);

Simulate Success Event

Send a successful payment webhook:

await simulateWebhook('SUCCESS');

Check your webhook endpoint receives and processes the notification correctly.

Simulate Declined Event

Send a declined payment webhook:

await simulateWebhook('MISSING_DESTINATION_ACCOUNT');

Verify your endpoint handles payment failures gracefully.

Test Error Scenarios

Test your webhook error handling:

Return 5xx status to trigger retries
Delay response beyond 10 seconds to test timeouts
Verify idempotency by sending duplicate webhooks

Verify Decryption

Confirm your endpoint can decrypt JWE payloads successfully using your secret key.

Use Cases

Initial Integration Testing

Test your webhook handler during development:

console.log('Testing webhook integration...');

// Test success case
await simulateWebhook('SUCCESS');
await wait(2000);

// Test decline case
await simulateWebhook('MISSING_DESTINATION_ACCOUNT');
await wait(2000);

console.log('Webhook integration test complete');

CI/CD Automated Testing

Include webhook simulation in your test suite:

describe('Webhook Integration', () => {
  it('should handle successful payments', async () => {
    const result = await simulateWebhook('SUCCESS');
    expect(result.webhooksSent).toBeGreaterThan(0);

    // Wait for webhook to be processed
    await wait(3000);

    // Verify order was marked as paid
    const order = await db.orders.findOne({ status: 'paid' });
    expect(order).toBeDefined();
  });

  it('should handle declined payments', async () => {
    const result = await simulateWebhook('MISSING_DESTINATION_ACCOUNT');
    expect(result.webhooksSent).toBeGreaterThan(0);

    // Verify order was marked as failed
    await wait(3000);
    const order = await db.orders.findOne({ status: 'payment_failed' });
    expect(order).toBeDefined();
  });
});

Verify Decryption Implementation

Test your JWE decryption logic:

// Send simulated webhook
await simulateWebhook('SUCCESS');

// Check server logs to verify decryption succeeded
console.log('Check your webhook endpoint logs for:');
console.log('- JWE decryption success message');
console.log('- Decrypted payload structure');
console.log('- Webhook processing result');

Test Error Handling

Verify your webhook handler manages errors gracefully:

// Test idempotency by sending same webhook twice
await simulateWebhook('SUCCESS');
await wait(1000);
await simulateWebhook('SUCCESS');

// Verify duplicate webhook was ignored
// (should only process once)

Demo and Presentations

Demonstrate webhook functionality without real transactions:

console.log('Starting live webhook demo...');

// Simulate successful payment
console.log('Simulating successful payment...');
await simulateWebhook('SUCCESS');

await wait(2000);

// Simulate declined payment
console.log('Simulating declined payment...');
await simulateWebhook('MISSING_DESTINATION_ACCOUNT');

console.log('Demo complete!');

Testing Checklist

Best Practices

Test Both Scenarios

Always test both success and decline webhooks:

async function runFullWebhookTest() {
  // Test success
  await simulateWebhook('SUCCESS');
  await verifySuccessHandling();

  // Test declined
  await simulateWebhook('MISSING_DESTINATION_ACCOUNT');
  await verifyDeclineHandling();

  console.log('All webhook tests passed');
}

Use in CI/CD

Automate webhook testing in your deployment pipeline:

# .github/workflows/test.yml
- name: Test Webhook Integration
  run: |
    npm run start:test-server &
    sleep 5
    npm run test:webhooks

Monitor Test Results

Track webhook simulation outcomes:

const testResults = {
  successTests: 0,
  declinedTests: 0,
  failures: 0
};

try {
  await simulateWebhook('SUCCESS');
  testResults.successTests++;
} catch (error) {
  testResults.failures++;
}

console.log('Test results:', testResults);

Test with Delays

Allow time for webhook processing between tests:

await simulateWebhook('SUCCESS');
await wait(2000); // Wait 2 seconds

await simulateWebhook('MISSING_DESTINATION_ACCOUNT');
await wait(2000);

// Now verify results

Differences from Real Webhooks

Aspect	Simulate API	Real Webhooks
Trigger	Manual API call	Actual QR Ph transaction
Reference Number	`SIM-REF-*` prefix	Real reference from QR creation
Transaction Data	Test data	Real customer payment data
Timing	Immediate	Depends on payment processing
Retries	Same as real	Up to 4 attempts (0, 15, 30, 45 min)
Encryption	JWE encrypted	JWE encrypted
Availability	Sandbox only	Sandbox and production

Simulated webhooks behave identically to real webhooks except for the data content. Your webhook handler should process them the same way.

Troubleshooting

404: No Enabled Webhooks Found

Symptom: Receive 404 error when calling Simulate APIPossible Causes:

No webhooks registered
All webhooks are disabled
Webhook actions don’t include the simulated event

Solutions:

// Check existing webhooks
const webhooks = await getWebhooks();
console.log('Webhooks:', webhooks);

// Ensure at least one is enabled
const enabled = webhooks.filter(w => w.status === 'ENABLED');

if (enabled.length === 0) {
  // Create or enable a webhook
  await createWebhook(
    'https://your-server.com/webhooks',
    ['QRPH_SUCCESS', 'QRPH_DECLINED'],
    'ENABLED'
  );
}

Webhook Not Received

Symptom: Simulate API returns success but webhook not receivedPossible Causes:

Webhook URL not accessible
Firewall blocking requests
Endpoint not listening

Solutions:

Test webhook URL accessibility externally
Check server logs for incoming requests
Verify endpoint is running and listening
Test with ngrok or similar during development

Decryption Fails

Symptom: Webhook received but cannot decrypt payloadPossible Causes:

Wrong secret key
JWE library issue
Incorrect algorithm configuration

Solutions:

// Verify secret key
console.log('Secret key length:', SECRET_KEY.length);
console.log('Secret key starts with:', SECRET_KEY.substring(0, 3));

// Test decryption
try {
  const payload = await decryptWebhook(webhookData, SECRET_KEY);
  console.log('Decryption successful:', payload);
} catch (error) {
  console.error('Decryption failed:', error);
}

Multiple Webhooks Sent

Symptom: Receive multiple webhook deliveries for one simulationCause: Multiple enabled webhooks registeredExpected Behavior: The Simulate API sends notifications to all enabled webhooks that are configured for the simulated event.Verification:

const result = await simulateWebhook('SUCCESS');
console.log(`Webhooks sent: ${result.webhooksSent}`);
// This tells you how many webhooks received the notification

Next Steps

Create Webhook

Receiving Webhooks

Implement webhook processing logic

Payload Structure

Understand webhook payload format

Setup Guide

Complete webhook integration guide

Authorizations

Authorization

string

header

required

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

Body

application/json

request

object

required

Show child attributes

Response

Webhook simulation sent successfully

string

The unique identifier of the original transaction (i.e., the id returned from the Create Dynamic QR Ph response).

Delete Webhook Ping

⌘I

​Overview

​Endpoint

​Authentication

​Request

​Headers

​Body Parameters (Encrypted Payload)

​Example Payloads (Before Encryption)

​Response

​Success Response

​Response Example

​Error Responses

​Testing Workflow

​Use Cases

​Testing Checklist

​Best Practices

Test Both Scenarios

Use in CI/CD

Monitor Test Results

Test with Delays

​Differences from Real Webhooks

​Troubleshooting

​Next Steps

Create Webhook

Receiving Webhooks

Payload Structure

Setup Guide

Authorizations

Body

Response

Overview

Endpoint

Authentication

Request

Headers

Body Parameters (Encrypted Payload)

Example Payloads (Before Encryption)

Response

Success Response

Response Example

Error Responses

Testing Workflow

Use Cases

Testing Checklist

Best Practices

Differences from Real Webhooks

Troubleshooting

Next Steps