Skip to main content

​
Endpoint

DELETE /hooks/:id
Deletes a webhook, permanently removing it from the system. The webhook will no longer receive events.

​
Path Parameters

​
id
string
required
The unique identifier of the webhook to delete

​
Response

​
message
string
Confirmation message that the webhook was deleted successfully

​
Example Request

curl -X DELETE "https://api.blnk.io/hooks/hook_abc123def456" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Example Response

{
  "message": "hook deleted successfully"
}

​
Error Responses

​
error
string
Error message describing what went wrong

​
Common Errors

  • 400 Bad Request: Invalid webhook ID
  • 404 Not Found: Webhook not found
  • 500 Internal Server Error: Failed to delete webhook

​
Important Considerations

​
Permanent Deletion

This operation is permanent and cannot be undone. Once a webhook is deleted:
  • It will no longer receive any events
  • All configuration is permanently removed
  • The webhook ID cannot be reused

​
Alternative: Deactivation

If you want to temporarily stop a webhook without deleting it, consider using the Update Webhook endpoint to deactivate it instead: 
{
  "active": false
}
This allows you to reactivate the webhook later without reconfiguring it.

​
Use Cases

​
Remove Deprecated Webhooks

Delete webhooks that are no longer in use: 
const removeDeprecatedWebhook = async (hookId) => {
  // Optional: Get webhook details first for logging
  const webhook = await getWebhook(hookId);
  console.log(`Deleting webhook: ${webhook.name}`);
  
  const response = await fetch(`https://api.blnk.io/hooks/${hookId}`, {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });
  
  if (response.ok) {
    console.log('Webhook deleted successfully');
  }
};

​
Clean Up Test Webhooks

Remove webhooks created during testing: 
const cleanupTestWebhooks = async () => {
  // Get all webhooks
  const webhooks = await fetch('https://api.blnk.io/hooks', {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }).then(r => r.json());
  
  // Find test webhooks (e.g., containing 'test' in name)
  const testWebhooks = webhooks.filter(h => 
    h.name.toLowerCase().includes('test')
  );
  
  // Delete each test webhook
  for (const webhook of testWebhooks) {
    await fetch(`https://api.blnk.io/hooks/${webhook.id}`, {
      method: 'DELETE',
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    });
    console.log(`Deleted test webhook: ${webhook.name}`);
  }
};

​
Webhook Lifecycle Management

Manage webhook lifecycle with proper deletion: 
const webhookLifecycle = {
  async create(config) {
    const response = await fetch('https://api.blnk.io/hooks', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(config)
    });
    return response.json();
  },
  
  async deactivate(hookId) {
    const response = await fetch(`https://api.blnk.io/hooks/${hookId}`, {
      method: 'PUT',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ active: false })
    });
    return response.json();
  },
  
  async delete(hookId) {
    const response = await fetch(`https://api.blnk.io/hooks/${hookId}`, {
      method: 'DELETE',
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    });
    return response.json();
  }
};

​
Safe Deletion with Confirmation

Implement confirmation before deletion: 
const safeDeleteWebhook = async (hookId) => {
  // Get webhook details
  const webhook = await fetch(`https://api.blnk.io/hooks/${hookId}`, {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }).then(r => r.json());
  
  // Show confirmation (example for Node.js CLI)
  console.log('\nWebhook to delete:');
  console.log(`  Name: ${webhook.name}`);
  console.log(`  URL: ${webhook.url}`);
  console.log(`  Type: ${webhook.type}`);
  console.log(`  Active: ${webhook.active}`);
  
  // In a real application, get user confirmation
  const confirmed = true; // Replace with actual confirmation logic
  
  if (confirmed) {
    const response = await fetch(`https://api.blnk.io/hooks/${hookId}`, {
      method: 'DELETE',
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    });
    
    if (response.ok) {
      console.log('\n✓ Webhook deleted successfully');
    }
  } else {
    console.log('\n✗ Deletion cancelled');
  }
};

​
Best Practices

  1. Verify before deleting: Get webhook details first to confirm you’re deleting the right one
  2. Consider deactivation: Use deactivation instead of deletion for temporary stops
  3. Document deletions: Log when and why webhooks are deleted
  4. Remove in order: Delete dependent webhooks before parent resources
  5. Clean up regularly: Periodically review and remove unused webhooks

​
Deactivation vs Deletion

ActionReversiblePreserves ConfigUse When
DeactivationYesYesTemporary pause, testing, maintenance
DeletionNoNoPermanent removal, cleanup, endpoint no longer exists

​
When to Delete vs Deactivate

​
Delete When:

  • The webhook endpoint no longer exists
  • The integration has been completely removed
  • The webhook was created for testing only
  • You’re cleaning up old, unused configurations
  • The webhook has been replaced by a new one

​
Deactivate When:

  • Performing maintenance on the webhook endpoint
  • Testing other webhooks without interference
  • The endpoint is temporarily unavailable
  • You want to keep the configuration for future use
  • Debugging webhook issues

Build docs developers (and LLMs) love

Get started for freeTalk to us