The List Webhooks endpoint allows you to retrieve all webhook endpoints associated with your application. This endpoint provides comprehensive information about each webhook including delivery statistics and configuration details.

​
Endpoint Details

  • URL: /api/v0/webhooks
  • Method: GET
  • Authentication: Required (API Key Authentication with Scopes)
  • Content-Type: application/json
  • Required Scope: webhook:read

​
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:read scope to access this endpoint.

​
Query Parameters

ParameterTypeDescriptionDefaultExample
pageintegerPage number for pagination1?page=2
limitintegerNumber of webhooks per page (1-100)20?limit=50
activebooleanFilter by active statusall?active=true

​
Response

​
Success Response (200 OK)

{
  "data": [
    {
      "id": "wh_550e8400e29b41d4a716446655440000",
      "name": "Payment Notifications",
      "url": "https://api.example.com/webhooks/payments",
      "isActive": true,
      "encrypted": false,
      "signing_secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
      "created_at": "2024-03-15T10:30:00.000Z",
      "updated_at": "2024-03-20T14:45:00.000Z",
      "delivery_stats": {
        "total_events": 1250,
        "successful_deliveries": 1235,
        "failed_deliveries": 15,
        "last_delivery": "2024-03-20T14:30:00.000Z",
        "success_rate": 98.8
      },
      "app": {
        "id": "app_123e4567e89b12d3a456426614174000",
        "name": "Your App Name"
      }
    },
    {
      "id": "wh_660f9500f30c52e5b827557766551111",
      "name": "Order Updates",
      "url": "https://api.example.com/webhooks/orders",
      "isActive": true,
      "encrypted": true,
      "signing_secret": "whsec_b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7",
      "created_at": "2024-03-18T09:15:00.000Z",
      "updated_at": "2024-03-20T16:20:00.000Z",
      "delivery_stats": {
        "total_events": 850,
        "successful_deliveries": 845,
        "failed_deliveries": 5,
        "last_delivery": "2024-03-20T16:15:00.000Z",
        "success_rate": 99.4
      },
      "app": {
        "id": "app_123e4567e89b12d3a456426614174000",
        "name": "Your App Name"
      }
    },
    {
      "id": "wh_770g0611g41d63f6c938668877662222",
      "name": "Test Webhook",
      "url": "https://webhook.site/test-endpoint",
      "isActive": false,
      "encrypted": false,
      "signing_secret": "whsec_c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8",
      "created_at": "2024-03-19T11:45:00.000Z",
      "updated_at": "2024-03-19T11:45:00.000Z",
      "delivery_stats": {
        "total_events": 0,
        "successful_deliveries": 0,
        "failed_deliveries": 0,
        "last_delivery": null,
        "success_rate": 0
      },
      "app": {
        "id": "app_123e4567e89b12d3a456426614174000",
        "name": "Your App Name"
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 3,
    "per_page": 20,
    "has_next": false,
    "has_previous": false
  }
}

​
Response Fields

​
Webhook Object

FieldTypeDescription
idstringUnique identifier for the webhook
namestringHuman-readable name for the webhook
urlstringEndpoint URL where events are sent
isActivebooleanWhether the webhook is currently active
encryptedbooleanWhether payloads are encrypted
signing_secretstringSecret used for signature verification
created_atstringISO 8601 timestamp when webhook was created
updated_atstringISO 8601 timestamp when webhook was last updated
delivery_statsobjectStatistics about webhook deliveries
appobjectApplication information

​
Delivery Stats Object

FieldTypeDescription
total_eventsnumberTotal number of events sent to this webhook
successful_deliveriesnumberNumber of successfully delivered events
failed_deliveriesnumberNumber of failed delivery attempts
last_deliverystringISO 8601 timestamp of last delivery attempt
success_ratenumberDelivery success rate percentage

​
Example Requests

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

​
Error Responses

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

​
Filtering and Pagination

​
Pagination

  • page: Page number (starting from 1)
  • limit: Items per page (1-100, default: 20)
  • Response includes: Current page, total pages, total count, navigation flags
"pagination": {
  "current_page": 1,
  "total_pages": 3,
  "total_count": 45,
  "per_page": 20,
  "has_next": true,
  "has_previous": false
}

​
Filtering

  • active=true: Show only active webhooks
  • active=false: Show only inactive webhooks
  • No filter: Show all webhooks regardless of status
Additional filtering options coming soon:
  • Filter by creation date range
  • Filter by delivery success rate
  • Search by webhook name or URL

​
Webhook Management

Monitor Performance

Track delivery success rates and identify failing webhooks

Manage Configuration

Review webhook settings and update configurations as needed

Debug Issues

Analyze delivery statistics to troubleshoot webhook problems

Audit Activity

Review webhook creation and modification history

​
Use Cases

​
Webhook Health Monitoring

const monitorWebhookHealth = async () => {
  const webhooks = await getWebhooks();
  
  const unhealthyWebhooks = webhooks.data.filter(webhook => {
    const stats = webhook.delivery_stats;
    return stats.success_rate < 95 && stats.total_events > 10;
  });
  
  if (unhealthyWebhooks.length > 0) {
    console.log('Unhealthy webhooks detected:');
    unhealthyWebhooks.forEach(webhook => {
      console.log(`- ${webhook.name}: ${webhook.delivery_stats.success_rate}% success rate`);
    });
    
    // Send alert to monitoring system
    await sendHealthAlert(unhealthyWebhooks);
  }
};

​
Configuration Audit

const auditWebhookConfiguration = async () => {
  const webhooks = await getWebhooks();
  
  const auditReport = {
    total: webhooks.data.length,
    active: webhooks.data.filter(w => w.isActive).length,
    encrypted: webhooks.data.filter(w => w.encrypted).length,
    with_custom_secrets: webhooks.data.filter(w => w.signing_secret?.startsWith('whsec_')).length,
    https_endpoints: webhooks.data.filter(w => w.url.startsWith('https://')).length
  };
  
  console.log('Webhook Configuration Audit:', auditReport);
  
  // Check for security recommendations
  const recommendations = [];
  
  if (auditReport.https_endpoints < auditReport.total) {
    recommendations.push('Consider using HTTPS for all webhook endpoints');
  }
  
  if (auditReport.encrypted < auditReport.total) {
    recommendations.push('Consider enabling encryption for sensitive webhooks');
  }
  
  return { auditReport, recommendations };
};

​
Best Practices

1

Regular Health Checks

Monitor webhook delivery statistics regularly to identify and resolve issues quickly.
2

Pagination for Scale

Use pagination when dealing with large numbers of webhooks to improve performance.
3

Filter Efficiently

Use status filters to focus on specific webhook categories for management tasks.
4

Monitor Success Rates

Set up alerts for webhooks with success rates below acceptable thresholds.
5

Security Audit

Regularly audit webhook configurations for security best practices.
  • POST /api/v0/webhooks - Create a new webhook
  • GET /api/v0/webhooks/{id} - Fetch specific webhook details
  • PATCH /api/v0/webhooks/{id} - Update webhook configuration
  • DELETE /api/v0/webhooks/{id} - Delete webhook