The Delete Webhook endpoint allows you to permanently remove webhook endpoints from your application. Once deleted, the webhook will no longer receive events and cannot be recovered. This operation is irreversible, so use it carefully.

​
Endpoint Details

  • URL: /api/v0/webhooks/{webhook_id}
  • Method: DELETE
  • Authentication: Required (API Key Authentication with Scopes)
  • Content-Type: application/json
  • Required Scope: webhook:delete

​
Authentication

This endpoint requires API key authentication with specific scopes:

​
Required Headers

x-client-key: your-client-key
x-client-secret: your-client-secret

​
Required Scope

Your API key must have the webhook:delete scope to access this endpoint.

​
Path Parameters

ParameterTypeDescriptionRequired
webhook_idstringUnique identifier for webhookYes

​
Response

​
Success Response (204 No Content)

When a webhook is successfully deleted, the API returns a 204 No Content status with an empty response body. This indicates that the webhook has been permanently removed.

​
Confirmation Response (200 OK)

Some implementations may return a confirmation response: 
{
  "message": "Webhook successfully deleted",
  "webhook_id": "wh_550e8400e29b41d4a716446655440000",
  "deleted_at": "2024-03-20T15:30:00.000Z"
}

​
Example Requests

curl -X DELETE "https://api.devdraft.ai/api/v0/webhooks/wh_550e8400e29b41d4a716446655440000" \
  -H "Content-Type: application/json" \
  -H "x-client-key: your-client-key" \
  -H "x-client-secret: your-client-secret"

​
Error Responses

{
  "statusCode": 404,
  "message": "Webhook not found",
  "error": "Not Found",
  "details": "No webhook found with ID: wh_550e8400e29b41d4a716446655440000"
}

​
Safety Considerations

Irreversible Action: Once a webhook is deleted, it cannot be recovered. All configuration and delivery history will be permanently lost.
Active Deliveries: Deleting a webhook may interrupt pending event deliveries. Consider disabling the webhook first and waiting for pending deliveries to complete.

​
Pre-Deletion Checklist

1

Verify Webhook ID

Double-check the webhook ID to ensure you’re deleting the correct webhook.
2

Check Dependencies

Verify that no critical processes depend on this webhook for functionality.
3

Review Recent Activity

Check recent delivery events to ensure no important events are in progress.
4

Backup Configuration

Note down webhook configuration (URL, settings) in case you need to recreate it.
5

Inform Team

Notify relevant team members about the webhook deletion, especially if it’s shared.

​
Alternative Actions

Before deleting a webhook, consider these alternatives:
Temporary Solution: Disable the webhook by setting isActive: false instead of deleting it.
// Disable webhook instead of deleting
await updateWebhook(webhookId, { isActive: false });
Benefits:
  • Preserves configuration and history
  • Can be easily re-enabled later
  • Safer than permanent deletion
Redirect to New Endpoint: Update the webhook URL to point to a new endpoint.
// Update webhook URL
await updateWebhook(webhookId, { 
  url: 'https://new-endpoint.example.com/webhooks' 
});
Use Cases:
  • Moving to a new server
  • Changing webhook implementation
  • Temporary redirects
Export Settings: Save webhook configuration before deletion for future reference.
// Export webhook configuration
const webhook = await getWebhook(webhookId);
const config = {
  name: webhook.name,
  url: webhook.url,
  encrypted: webhook.encrypted,
  // Save other important settings
};
console.log('Webhook config:', JSON.stringify(config, null, 2));

​
Batch Operations

​
Delete Multiple Webhooks

const deleteMultipleWebhooks = async (webhookIds) => {
  const results = [];
  
  for (const webhookId of webhookIds) {
    try {
      await deleteWebhook(webhookId);
      results.push({ 
        webhookId, 
        status: 'deleted', 
        error: null 
      });
    } catch (error) {
      results.push({ 
        webhookId, 
        status: 'failed', 
        error: error.message 
      });
    }
  }
  
  return results;
};

// Usage
const webhooksToDelete = [
  'wh_550e8400e29b41d4a716446655440000',
  'wh_660f9500f30c52e5b827557766551111'
];

const results = await deleteMultipleWebhooks(webhooksToDelete);
console.log('Deletion results:', results);

​
Cleanup Unused Webhooks

const cleanupUnusedWebhooks = async (criteria = {}) => {
  const {
    inactiveDays = 30,
    zeroDeliveries = true,
    confirmBeforeDelete = true
  } = criteria;
  
  // Get all webhooks
  const webhooks = await listWebhooks();
  
  // Filter based on criteria
  const cutoffDate = new Date();
  cutoffDate.setDate(cutoffDate.getDate() - inactiveDays);
  
  const candidatesForDeletion = webhooks.data.filter(webhook => {
    const lastDelivery = new Date(webhook.delivery_stats.last_delivery || 0);
    const hasNoDeliveries = webhook.delivery_stats.total_events === 0;
    const isOldAndInactive = lastDelivery < cutoffDate;
    
    return (zeroDeliveries && hasNoDeliveries) || isOldAndInactive;
  });
  
  console.log(`Found ${candidatesForDeletion.length} webhooks for cleanup:`);
  candidatesForDeletion.forEach(webhook => {
    console.log(`- ${webhook.name} (${webhook.id}) - Last delivery: ${webhook.delivery_stats.last_delivery || 'Never'}`);
  });
  
  if (confirmBeforeDelete) {
    const confirm = prompt('Delete these webhooks? (yes/no): ');
    if (confirm !== 'yes') {
      console.log('Cleanup cancelled');
      return [];
    }
  }
  
  // Delete webhooks
  return await deleteMultipleWebhooks(candidatesForDeletion.map(w => w.id));
};

// Run cleanup
await cleanupUnusedWebhooks({
  inactiveDays: 60,
  zeroDeliveries: true,
  confirmBeforeDelete: true
});

​
Best Practices

  • Always implement a confirmation step for deletion operations
  • Display webhook details before deletion to prevent mistakes
  • Consider requiring additional authentication for bulk deletions
  • Log all webhook deletions for audit purposes
  • Include user information, timestamp, and reason for deletion
  • Maintain deletion logs for compliance and troubleshooting
  • Check for pending deliveries before deletion
  • Consider disabling webhook first, then deleting after grace period
  • Implement proper error handling for deletion failures
  • Export webhook configurations before deletion
  • Store critical webhook settings in version control
  • Document webhook purposes and dependencies

​
Use Cases

​
Development Environment Cleanup

const cleanupDevelopmentWebhooks = async () => {
  const webhooks = await listWebhooks();
  
  // Find development/test webhooks
  const devWebhooks = webhooks.data.filter(webhook => 
    webhook.name.toLowerCase().includes('test') ||
    webhook.name.toLowerCase().includes('dev') ||
    webhook.url.includes('localhost') ||
    webhook.url.includes('webhook.site')
  );
  
  console.log(`Found ${devWebhooks.length} development webhooks`);
  
  // Delete development webhooks
  for (const webhook of devWebhooks) {
    try {
      await deleteWebhook(webhook.id);
      console.log(`Deleted development webhook: ${webhook.name}`);
    } catch (error) {
      console.error(`Failed to delete ${webhook.name}: ${error.message}`);
    }
  }
};

​
Migration Cleanup

const cleanupAfterMigration = async (oldUrlPattern) => {
  const webhooks = await listWebhooks();
  
  // Find webhooks pointing to old infrastructure
  const oldWebhooks = webhooks.data.filter(webhook => 
    webhook.url.includes(oldUrlPattern)
  );
  
  console.log(`Found ${oldWebhooks.length} webhooks using old URLs`);
  
  // Confirm each deletion individually for migration cleanup
  for (const webhook of oldWebhooks) {
    console.log(`\nWebhook: ${webhook.name}`);
    console.log(`URL: ${webhook.url}`);
    console.log(`Last delivery: ${webhook.delivery_stats.last_delivery || 'Never'}`);
    
    const action = prompt('Action (delete/skip/update): ');
    
    if (action === 'delete') {
      await deleteWebhook(webhook.id);
      console.log('Deleted');
    } else if (action === 'update') {
      const newUrl = prompt('New URL: ');
      if (newUrl) {
        await updateWebhook(webhook.id, { url: newUrl });
        console.log('Updated');
      }
    } else {
      console.log('Skipped');
    }
  }
};
  • POST /api/v0/webhooks - Create a new webhook
  • GET /api/v0/webhooks - List all webhooks
  • GET /api/v0/webhooks/{id} - Fetch specific webhook details
  • PATCH /api/v0/webhooks/{id} - Update webhook configuration