Delete Webhook - Modulus Labs API

curl -X DELETE https://webhooks.sbx.moduluslabs.io/v1/webhooks/123 \
  -u sk_your_secret_key:

DELETE

webhooks

{id}

curl -X DELETE https://webhooks.sbx.moduluslabs.io/v1/webhooks/123 \
  -u sk_your_secret_key:

Overview

The Delete Webhook endpoint permanently removes a registered webhook. After deletion, you’ll stop receiving notifications for transactions. This action cannot be undone.

Permanent Action: Deleting a webhook is irreversible. Consider disabling the webhook instead if you might need it again later.

Endpoint

DELETE 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

integer

required

The unique identifier of the webhook to delete. You can get this ID from the Get Webhooks API or from the response when you created the webhook.Example: 123

Headers

Header	Value	Required
`Authorization`	`Basic {base64(secret_key:)}`	Yes

Request Body

This endpoint does not require a request body.

Response

Success Response

Status Code: 204 No Content Returns an empty response body. The webhook has been successfully deleted.

Success: A 204 status code means the webhook was deleted. You’ll no longer receive notifications at that URL.

Error Responses

401 Unauthorized

Status Code: 401Cause: Invalid or missing authentication credentialsResponse Example:

{
  "code": "20000001",
  "error": "Invalid or missing secret key",
  "referenceNumber": "abc123-def456-ghi789"
}

Solution:

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

404 Not Found

Status Code: 404Cause: Webhook ID does not exist or was already deletedResponse 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 already deleted

500 Internal Server Error

Status Code: 500Cause: Unexpected server errorSolution:

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

curl -X DELETE https://webhooks.sbx.moduluslabs.io/v1/webhooks/123 \
  -u sk_your_secret_key:

Use Cases

Decommission Old Webhook

Remove webhooks for decommissioned services or endpoints:

// Get all webhooks
const webhooks = await getWebhooks();

// Find webhooks for old domain
const oldWebhooks = webhooks.filter(w =>
  w.webhookUrl.includes('old-domain.com')
);

// Delete them
for (const webhook of oldWebhooks) {
  await deleteWebhook(webhook.id);
  console.log(`Deleted old webhook: ${webhook.webhookUrl}`);
}

Clean Up Test Webhooks

Remove webhooks created during development and testing:

const webhooks = await getWebhooks();

// Find test webhooks
const testWebhooks = webhooks.filter(w =>
  w.webhookUrl.includes('localhost') ||
  w.webhookUrl.includes('ngrok') ||
  w.webhookUrl.includes('test')
);

// Delete test webhooks
for (const webhook of testWebhooks) {
  await deleteWebhook(webhook.id);
  console.log(`Deleted test webhook: ${webhook.id}`);
}

Replace Webhook Configuration

Delete old webhook before creating a new one with the same URL:

const newUrl = 'https://api.example.com/webhooks/modulus';

// Check if webhook with this URL already exists
const webhooks = await getWebhooks();
const existing = webhooks.find(w => w.webhookUrl === newUrl);

if (existing) {
  // Delete old webhook
  await deleteWebhook(existing.id);
  console.log('Deleted existing webhook');
}

// Create new webhook
const newWebhook = await createWebhook(
  newUrl,
  ['QRPH_SUCCESS', 'QRPH_DECLINED'],
  'ENABLED'
);

console.log('Created new webhook:', newWebhook.id);

Remove Duplicate Webhooks

Clean up accidentally created duplicate webhooks:

const webhooks = await getWebhooks();

// Group webhooks by URL
const grouped = webhooks.reduce((acc, webhook) => {
  acc[webhook.webhookUrl] = acc[webhook.webhookUrl] || [];
  acc[webhook.webhookUrl].push(webhook);
  return acc;
}, {});

// Delete duplicates (keep the newest)
for (const url in grouped) {
  const duplicates = grouped[url];

  if (duplicates.length > 1) {
    // Sort by creation date, keep newest
    duplicates.sort((a, b) =>
      new Date(b.createdAt) - new Date(a.createdAt)
    );

    // Delete older duplicates
    for (let i = 1; i < duplicates.length; i++) {
      await deleteWebhook(duplicates[i].id);
      console.log(`Deleted duplicate webhook: ${duplicates[i].id}`);
    }
  }
}

Switch Environments

Remove sandbox webhooks when migrating to production:

// Get sandbox webhooks
const sandboxWebhooks = await getSandboxWebhooks();

// Delete all sandbox webhooks
for (const webhook of sandboxWebhooks) {
  await deleteWebhook(webhook.id);
  console.log(`Deleted sandbox webhook: ${webhook.id}`);
}

console.log('Sandbox webhooks cleaned up, ready for production');

Best Practices

Disable Before Deleting

Disable webhook first, monitor for issues, then delete:

// Step 1: Disable webhook
await updateWebhook(webhookId, { status: 'DISABLED' });
console.log('Webhook disabled');

// Step 2: Monitor for 24 hours...
await wait(86400000);

// Step 3: Delete if no issues
await deleteWebhook(webhookId);
console.log('Webhook deleted');

Verify Before Deleting

Confirm webhook details before deletion:

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

console.log('About to delete:', webhook.webhookUrl);

// Require confirmation in production
if (process.env.NODE_ENV === 'production') {
  const confirmed = await promptConfirmation(
    `Delete webhook ${webhook.webhookUrl}?`
  );

  if (!confirmed) {
    console.log('Deletion cancelled');
    return;
  }
}

await deleteWebhook(webhookId);

Log Deletions

Track webhook deletions for audit purposes:

async function deleteWebhookWithAudit(webhookId) {
  // Get webhook details before deleting
  const webhooks = await getWebhooks();
  const webhook = webhooks.find(w => w.id === webhookId);

  // Delete webhook
  await deleteWebhook(webhookId);

  // Log deletion
  await db.webhookAudit.insert({
    action: 'deleted',
    webhookId: webhookId,
    webhookUrl: webhook.webhookUrl,
    deletedAt: new Date(),
    deletedBy: getCurrentUser()
  });

  console.log(`Webhook ${webhookId} deleted and logged`);
}

Consider Alternatives

Ask yourself: Should I disable instead of delete?Disable if:

You might need the webhook again
Temporarily troubleshooting
Server maintenance

Delete if:

Service permanently decommissioned
Webhook created by mistake
Cleaning up old configurations

Safety Checklist

Before deleting a webhook in production:

What Happens After Deletion?

Immediate Effects

Webhook is immediately removed from your account
No more notifications will be sent to that URL
Webhook ID becomes invalid and cannot be reused
Cannot be undone - must create a new webhook if needed

Pending Notifications

Webhooks scheduled for retry may still be delivered
New transactions will not trigger notifications
In-flight webhook deliveries may complete

Recovery

If you deleted a webhook by mistake:

Create a new webhook with the same URL
Note: New webhook will have a different ID
Update any stored references to use the new ID
Test the new webhook with Simulate API

Troubleshooting

404 Error When Deleting

Symptom: Receive 404 when trying to delete webhookPossible Causes:

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

Solutions:

Call Get Webhooks API to verify webhook exists
Check webhook ID is correct
Verify you’re using the correct secret key

Deleted Webhook Still Receiving Notifications

Symptom: Webhook URL still receives POST requests after deletionPossible Causes:

Retries for transactions that occurred before deletion
Different webhook with same URL
Caching or replication delay (rare)

Solutions:

Wait for pending retries to complete (max 45 minutes)
Check if another webhook is using the same URL
Verify deletion succeeded by listing webhooks

Cannot Delete Last Webhook

Symptom: Want to delete all webhooks but concerned about losing notificationsConsideration: Webhooks are REQUIRED for QR Ph integration. Deleting all webhooks means you won’t receive transaction notifications.Solutions:

Ensure you have at least one active webhook
Create a new webhook before deleting the last one
Consider disabling instead of deleting

Comparison: Delete vs Disable

Action	Permanent	Reversible	Preserves Config	Use Case
Delete	Yes	No	No	Permanently remove unused webhook
Disable	No	Yes	Yes	Temporarily pause notifications

Recommendation: Use Update Webhook to disable webhooks during maintenance instead of deleting them. This preserves your configuration and makes it easy to resume.

Next Steps

Create Webhook

Update Webhook

Disable webhook instead of deleting

Get Webhooks

View remaining registered webhooks

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

Response

Webhook deleted successfully

message

string

Confirmation message

Update Webhook Simulate Webhook

⌘I

​Overview

​Endpoint

​Authentication

​Request

​Path Parameters

​Headers

​Request Body

​Response

​Success Response

​Error Responses

​Use Cases

​Best Practices

Disable Before Deleting

Verify Before Deleting

Log Deletions

Consider Alternatives

​Safety Checklist

​What Happens After Deletion?

​Troubleshooting

​Comparison: Delete vs Disable

​Next Steps

Create Webhook

Update Webhook

Get Webhooks

Webhooks Overview

Authorizations

Path Parameters

Response

Overview

Endpoint

Authentication

Request

Path Parameters

Headers

Request Body

Response

Success Response

Error Responses

Use Cases

Best Practices

Safety Checklist

What Happens After Deletion?

Troubleshooting

Comparison: Delete vs Disable

Next Steps