Delete Webhook

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

Parameter	Type	Description	Required
webhook_id	string	Unique identifier for webhook	Yes

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"

const deleteWebhook = async (webhookId) => {
  try {
    const response = await fetch(`https://api.devdraft.ai/api/v0/webhooks/${webhookId}`, {
      method: 'DELETE',
      headers: {
        'Content-Type': 'application/json',
        'x-client-key': process.env.DEVDRAFT_CLIENT_KEY,
        'x-client-secret': process.env.DEVDRAFT_CLIENT_SECRET
      }
    });

    if (!response.ok) {
      throw new Error(`Failed to delete webhook: ${response.statusText}`);
    }

    console.log(`Webhook ${webhookId} successfully deleted`);
    return true;
  } catch (error) {
    console.error('Error deleting webhook:', error);
    throw error;
  }
};

// Safe deletion with confirmation
const safeDeleteWebhook = async (webhookId) => {
  try {
    // First, get webhook details for confirmation
    const webhook = await getWebhook(webhookId);
    console.log(`About to delete webhook: ${webhook.name} (${webhook.url})`);
    
    // Confirm deletion (you might want to add user confirmation here)
    const confirmed = true; // Replace with actual confirmation logic
    
    if (confirmed) {
      await deleteWebhook(webhookId);
      console.log('Webhook deleted successfully');
    } else {
      console.log('Deletion cancelled');
    }
  } catch (error) {
    console.error('Error in safe deletion:', error);
    throw error;
  }
};

// Usage
await deleteWebhook('wh_550e8400e29b41d4a716446655440000');

import requests
from typing import Optional

class WebhookManager:
    def __init__(self, client_key: str, client_secret: str, base_url: str = 'https://api.devdraft.ai'):
        self.client_key = client_key
        self.client_secret = client_secret
        self.base_url = base_url
        
    def delete_webhook(self, webhook_id: str) -> bool:
        headers = {
            'Content-Type': 'application/json',
            'x-client-key': self.client_key,
            'x-client-secret': self.client_secret
        }
        
        response = requests.delete(
            f"{self.base_url}/api/v0/webhooks/{webhook_id}",
            headers=headers
        )
        
        if response.status_code == 204:
            return True
        elif response.status_code == 200:
            return True
        else:
            response.raise_for_status()
            return False
    
    def safe_delete_webhook(self, webhook_id: str, confirm: bool = False) -> bool:
        """Safely delete webhook with confirmation"""
        if not confirm:
            # Get webhook details first
            webhook = self.get_webhook(webhook_id)
            print(f"WARNING: About to delete webhook '{webhook['name']}' ({webhook['url']})")
            print("This action cannot be undone!")
            
            # In a real application, you would prompt for user confirmation
            response = input("Are you sure you want to delete this webhook? (yes/no): ")
            if response.lower() != 'yes':
                print("Deletion cancelled")
                return False
        
        return self.delete_webhook(webhook_id)
    
    def cleanup_inactive_webhooks(self, dry_run: bool = True) -> list:
        """Clean up inactive webhooks"""
        webhooks = self.list_webhooks(active=False)
        inactive_webhooks = webhooks['data']
        
        if dry_run:
            print(f"Found {len(inactive_webhooks)} inactive webhooks that could be deleted:")
            for webhook in inactive_webhooks:
                print(f"- {webhook['name']} ({webhook['id']})")
            return inactive_webhooks
        
        deleted_webhooks = []
        for webhook in inactive_webhooks:
            try {
                if self.delete_webhook(webhook['id']):
                    deleted_webhooks.append(webhook)
                    print(f"Deleted inactive webhook: {webhook['name']}")
            except Exception as e:
                print(f"Failed to delete webhook {webhook['name']}: {e}")
        
        return deleted_webhooks

# Usage
webhook_manager = WebhookManager(
    client_key='your-client-key',
    client_secret='your-client-secret'
)

# Delete a specific webhook
webhook_manager.delete_webhook('wh_550e8400e29b41d4a716446655440000')

# Safe deletion with confirmation
webhook_manager.safe_delete_webhook('wh_550e8400e29b41d4a716446655440000')

# Clean up inactive webhooks (dry run first)
inactive = webhook_manager.cleanup_inactive_webhooks(dry_run=True)
print(f"Found {len(inactive)} inactive webhooks")

Error Responses

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

{
  "statusCode": 401,
  "message": "Client key or secret missing",
  "error": "Unauthorized",
  "details": "Please provide both x-client-key and x-client-secret headers"
}

{
  "statusCode": 403,
  "message": "Missing required scope",
  "error": "Forbidden",
  "details": "API key does not have the required webhook:delete scope"
}

{
  "statusCode": 409,
  "message": "Cannot delete webhook with pending deliveries",
  "error": "Conflict",
  "details": "Wait for pending deliveries to complete before deleting"
}

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

Verify Webhook ID

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

Check Dependencies

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

Review Recent Activity

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

Backup Configuration

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

Inform Team

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

Alternative Actions

Before deleting a webhook, consider these alternatives:

Disable Instead of Delete

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

Update URL

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

Archive Configuration

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

Confirmation Process

Always implement a confirmation step for deletion operations
Display webhook details before deletion to prevent mistakes
Consider requiring additional authentication for bulk deletions

Audit Logging

Log all webhook deletions for audit purposes
Include user information, timestamp, and reason for deletion
Maintain deletion logs for compliance and troubleshooting

Graceful Handling

Check for pending deliveries before deletion
Consider disabling webhook first, then deleting after grace period
Implement proper error handling for deletion failures

Backup Strategy

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

Home

Payment Intents

Webhooks

Wallets

Transfers

Endpoint Details

Authentication

Required Headers

Required Scope

Path Parameters

Response

Success Response (204 No Content)

Confirmation Response (200 OK)

Example Requests

Error Responses

Safety Considerations

Pre-Deletion Checklist

Alternative Actions

Batch Operations

Delete Multiple Webhooks

Cleanup Unused Webhooks

Best Practices

Use Cases

Development Environment Cleanup

Migration Cleanup

​Endpoint Details

​Authentication

​Required Headers

​Required Scope

​Path Parameters

​Response

​Success Response (204 No Content)

​Confirmation Response (200 OK)

​Example Requests

​Error Responses

​Safety Considerations

​Pre-Deletion Checklist

​Alternative Actions

​Batch Operations

​Delete Multiple Webhooks

​Cleanup Unused Webhooks

​Best Practices

​Use Cases

​Development Environment Cleanup

​Migration Cleanup

​Related Endpoints

Endpoint Details

Authentication

Required Headers

Required Scope

Path Parameters

Response

Success Response (204 No Content)

Confirmation Response (200 OK)

Example Requests

Error Responses

Safety Considerations

Pre-Deletion Checklist

Alternative Actions

Batch Operations

Delete Multiple Webhooks

Cleanup Unused Webhooks

Best Practices

Use Cases

Development Environment Cleanup

Migration Cleanup

Related Endpoints