Update 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: {"webhookStatus": "DISABLED"}
ENCRYPTED_TOKEN="eyJhbGciOiJBMjU2S1ciL..."

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

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

PUT

webhooks

{id}

# 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: {"webhookStatus": "DISABLED"}
ENCRYPTED_TOKEN="eyJhbGciOiJBMjU2S1ciL..."

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

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

Overview

The Update Webhook endpoint allows you to modify an existing webhook’s URL, actions, or status. Use this to change where notifications are sent, adjust which events you receive, or temporarily disable a webhook during maintenance.

Endpoint

PUT https://webhooks.sbx.moduluslabs.io/v1/webhooks/{id}

Authentication

This endpoint requires HTTP Basic Authentication using your Secret Key.

Authorization: Basic {base64(secret_key:)}

Request

Path Parameters

string

required

The unique identifier of the webhook to update. You can get this ID from the Get Webhooks API or from the response when you created the webhook.Example: "a78efd32-de3b-4854-b599-11ae9f98f97e"

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

Prerequisites

Before updating a webhook, ensure you have:

Your Secret Key for HTTP Basic Authentication
The webhook ID of the webhook you want to update

See the Encryption Guide to understand how JWE tokens work — you’ll need this to decrypt incoming webhook notifications, not for the Update Webhook API request itself.

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.

All body parameters are optional. Include only the fields you want to update. Fields you don’t include will remain unchanged.

Field	Type	Required	Description
`callbackUrl`	string	No	New HTTPS URL where Modulus Labs sends webhook notifications
`webhookAction`	string	No	Updated transaction events: `QRPH_SUCCESS`, `QRPH_DECLINED`
`webhookStatus`	string	No	New status: `ENABLED` or `DISABLED`

callbackUrl

The new 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/success"

webhookStatus

New webhook status:

ENABLED - Webhook receives notifications
DISABLED - Webhook stops receiving notifications (useful during maintenance)

Example: "DISABLED"

Use DISABLED during server maintenance instead of deleting the webhook. This preserves your configuration and makes it easy to resume.

Example Payloads (Before Encryption)

{
  "callbackUrl": "https://api.yourcompany.com/webhooks/success",
  "webhookStatus": "DISABLED"
}

Response

Success Response

Status Code: 200 OK Returns the updated webhook object with all current values.

string

Unique identifier for the webhook (unchanged).Example: "a78efd32-de3b-4854-b599-11ae9f98f97e"

webhookAction

string

String of webhook actions (updated or unchanged).Example: "QRPH_SUCCESS"

webhookStatus

string

Current webhook status (updated or unchanged).Example: "DISABLED"

callbackUrl

string

The webhook URL (updated or unchanged).Example: "https://api.yourcompany.com/webhooks/success"

Response Example

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

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

Error Responses

400 Bad Request

Status Code: 400Causes:

Invalid webhook URL format
Empty actions array
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
Include at least one valid action if updating actions
Verify 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:)}

404 Not Found

Status Code: 404Cause: Webhook ID does not existResponse Example:

{
  "code": "20000004",
  "error": "Webhook not found",
  "referenceNumber": "abc123-def456-ghi789"
}

Solutions:

Verify the webhook ID is correct
Use Get Webhooks API to find valid webhook IDs
Check if the webhook was deleted

409 Conflict

Status Code: 409Cause: New 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
Delete the existing webhook using that URL first

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: {"webhookStatus": "DISABLED"}
ENCRYPTED_TOKEN="eyJhbGciOiJBMjU2S1ciL..."

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

Use Cases

Temporarily Disable During Maintenance

Disable webhooks before server maintenance, enable after completion:

// Before maintenance
await updateWebhook(webhookId, { webhookStatus: 'DISABLED' });
console.log('Webhook disabled for maintenance');

// Perform maintenance...
await upgradeServer();

// After maintenance
await updateWebhook(webhookId, { webhookStatus: 'ENABLED' });
console.log('Webhook re-enabled');

Migrate to New Domain

Update webhook URL when changing domains or infrastructure:

// Update webhook to point to new domain
await updateWebhook(webhookId, {
  callbackUrl: 'https://new-domain.com/webhooks/modulus'
});

console.log('Webhook migrated to new domain');

Adjust Event Subscriptions

Change which events you want to receive:

// Only receive success events
await updateWebhook(webhookId, {
  webhookAction: 'QRPH_SUCCESS'
});

// Later: re-enable declined events
await updateWebhook(webhookId, {
  webhookAction: 'QRPH_SUCCESS', 'QRPH_DECLINED'
});

Switch to Versioned Endpoint

Update webhook URL to use a new API version:

await updateWebhook(webhookId, {
  callbackUrl: 'https://api.example.com/v2/webhooks/modulus'
});

console.log('Webhook updated to v2 endpoint');

Enable After Testing

Create disabled webhook for testing, enable when ready:

// Create disabled webhook
const webhook = await createWebhook(
  'https://api.example.com/webhooks/test',
  ['QRPH_SUCCESS', 'QRPH_DECLINED'],
  'DISABLED'
);

// Test with Simulate API
await simulateWebhook('SUCCESS');

// Enable after successful test
await updateWebhook(webhook.id, { webhookStatus: 'ENABLED' });
console.log('Webhook enabled after successful testing');

Best Practices

Verify Before Updating

Check current webhook configuration before updating:

const webhooks = await getWebhooks();
const webhook = webhooks.find(w => w.id === webhookId);

console.log('Current config:', webhook);

await updateWebhook(webhookId, { webhookStatus: 'DISABLED' });

Test New URL First

Verify new webhook URL is accessible before updating:

// Test new endpoint
try {
  await axios.post(newcallbackUrl, { test: true });
  console.log('New endpoint is accessible');

  // Update webhook
  await updateWebhook(webhookId, { callbackUrl: newcallbackUrl });
} catch (error) {
  console.error('New endpoint unreachable, skipping update');
}

Log All Changes

Track webhook configuration changes for audit purposes:

const oldConfig = await getWebhook(webhookId);

await updateWebhook(webhookId, updates);

const newConfig = await getWebhook(webhookId);

await db.webhookAudit.insert({
  webhookId,
  timestamp: new Date(),
  oldConfig,
  newConfig,
  updates
});

Graceful Status Changes

Notify your team before disabling production webhooks:

async function disableWebhook(webhookId, reason) {
  await alertTeam('Disabling webhook', { webhookId, reason });

  await updateWebhook(webhookId, { webhookStatus: 'DISABLED' });

  console.log(`Webhook ${webhookId} disabled: ${reason}`);
}

disableWebhook(123, 'Server maintenance scheduled');

Partial Updates

You only need to include fields you want to change:

// Update only the status (URL and actions remain unchanged)
await updateWebhook(123, {
  webhookStatus: 'DISABLED'
});

// Update only the URL (status and actions remain unchanged)
await updateWebhook(123, {
  callbackUrl: 'https://new-domain.com/webhooks'
});

// Update everything
await updateWebhook(123, {
  callbackUrl: 'https://new-domain.com/webhooks',
  webhookAction: 'QRPH_SUCCESS',
  webhookStatus: 'ENABLED'
});

Troubleshooting

404 Webhook Not Found

Symptom: Receive 404 error when updatingPossible Causes:

Wrong webhook ID
Webhook was deleted
Using wrong secret key (different merchant account)

Solutions:

Call Get Webhooks API to find valid webhook IDs
Verify you’re using the correct secret key
Check if webhook was deleted

409 Conflict on URL Change

Symptom: Receive 409 error when changing webhook URLCause: New URL is already registered for another webhookSolutions:

Use a different URL
Delete the other webhook using that URL first
Keep the current URL

Changes Not Taking Effect

Symptom: Webhook still receives old events or uses old URLPossible Causes:

Update request failed silently
Caching issue
Looking at wrong webhook

Solutions:

Verify update succeeded by checking response
Call Get Webhooks API to confirm changes
Clear any application caches

Next Steps

Delete Webhook

Permanently remove a webhook endpoint

Get Webhooks

View all registered webhooks

Test Webhook

Simulate webhooks to test your integration

Webhooks Overview

Learn about the Webhook API

Authorizations

Authorization

string

header

required

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

Path Parameters

string

required

The unique identifier of the webhook

Body

application/json

request

object

required

Show child attributes

Response

Webhook updated 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

Get Webhooks Delete Webhook

⌘I

​Overview

​Endpoint

​Authentication

​Request

​Path Parameters

​Headers

​Prerequisites

​Body Parameters (Encrypted Payload)

​Example Payloads (Before Encryption)

​Response

​Success Response

​Response Example

​Error Responses

​Use Cases

​Best Practices

Verify Before Updating

Test New URL First

Log All Changes

Graceful Status Changes

​Partial Updates

​Troubleshooting

​Next Steps

Delete Webhook

Get Webhooks

Test Webhook

Webhooks Overview

Authorizations

Path Parameters

Body

Response

Overview

Endpoint

Authentication

Request

Path Parameters

Headers

Prerequisites

Body Parameters (Encrypted Payload)

Example Payloads (Before Encryption)

Response

Success Response

Response Example

Error Responses

Use Cases

Best Practices

Partial Updates

Troubleshooting

Next Steps