The Fetch Webhook endpoint allows you to retrieve detailed information about a specific webhook, including its configuration, delivery statistics, and recent activity. This endpoint is useful for debugging webhook issues and monitoring individual webhook performance.

​
Endpoint Details

  • URL: /api/v0/webhooks/{webhook_id}
  • 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.

​
Path Parameters

ParameterTypeDescriptionRequired
webhook_idstringUnique identifier for webhookYes

​
Query Parameters

ParameterTypeDescriptionDefaultExample
include_eventsbooleanInclude recent delivery eventsfalse?include_events=true
events_limitintegerNumber of recent events to include (1-50)10?events_limit=20

​
Response

​
Success Response (200 OK)

{
  "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,
    "average_response_time": 145,
    "last_24h_events": 45,
    "last_24h_failures": 2
  },
  "app": {
    "id": "app_123e4567e89b12d3a456426614174000",
    "name": "Your App Name"
  },
  "recent_events": [
    {
      "id": "evt_789012345",
      "event_type": "payment.completed",
      "delivery_status": "delivered",
      "response_code": 200,
      "response_time": 125,
      "created_at": "2024-03-20T14:30:00.000Z",
      "delivered_at": "2024-03-20T14:30:01.000Z",
      "retry_count": 0
    },
    {
      "id": "evt_789012344",
      "event_type": "payment.failed",
      "delivery_status": "failed",
      "response_code": 500,
      "response_time": 30000,
      "error_message": "Internal Server Error",
      "created_at": "2024-03-20T14:25:00.000Z",
      "delivered_at": "2024-03-20T14:25:30.000Z",
      "retry_count": 3
    }
  ]
}

​
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_statsobjectDetailed statistics about webhook deliveries
appobjectApplication information
recent_eventsarrayRecent delivery events (if requested)

​
Enhanced Delivery Stats

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
average_response_timenumberAverage response time in milliseconds
last_24h_eventsnumberEvents sent in the last 24 hours
last_24h_failuresnumberFailed deliveries in the last 24 hours

​
Recent Event Object

FieldTypeDescription
idstringUnique identifier for the delivery event
event_typestringType of event that was delivered
delivery_statusstringStatus of delivery (delivered, failed, pending)
response_codenumberHTTP response code from webhook endpoint
response_timenumberResponse time in milliseconds
error_messagestringError message (if delivery failed)
created_atstringWhen the event was created
delivered_atstringWhen delivery was attempted
retry_countnumberNumber of retry attempts

​
Example Requests

curl -X GET "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"
}

​
Webhook Diagnostics

​
Health Indicators

  • Excellent: 99%+ success rate
  • Good: 95-99% success rate
  • Warning: 90-95% success rate
  • Critical: Below 90% success rate
  • Fast: Under 1 second average response time
  • Acceptable: 1-3 seconds average response time
  • Slow: 3-5 seconds average response time
  • Critical: Over 5 seconds average response time
  • Active: Events delivered in the last 24 hours
  • Idle: No events in the last 24 hours
  • Failing: Multiple failures in recent deliveries

​
Troubleshooting Guide

Common causes and solutions:
  • HTTP 4xx errors: Check webhook endpoint implementation
  • HTTP 5xx errors: Check webhook server health and capacity
  • Timeout errors: Optimize webhook response time
  • Connection errors: Verify webhook URL and network connectivity

​
Use Cases

​
Webhook Health Monitoring

const createWebhookDashboard = async (webhookId) => {
  const webhook = await getWebhook(webhookId, { includeEvents: true, eventsLimit: 50 });
  
  const dashboard = {
    webhook: {
      name: webhook.name,
      status: webhook.isActive ? 'Active' : 'Inactive',
      url: webhook.url,
      encrypted: webhook.encrypted
    },
    performance: {
      successRate: webhook.delivery_stats.success_rate,
      avgResponseTime: webhook.delivery_stats.average_response_time,
      last24hEvents: webhook.delivery_stats.last_24h_events,
      last24hFailures: webhook.delivery_stats.last_24h_failures
    },
    recentActivity: webhook.recent_events.map(event => ({
      type: event.event_type,
      status: event.delivery_status,
      time: event.created_at,
      responseTime: event.response_time
    }))
  };
  
  return dashboard;
};

​
Performance Analysis

const analyzeWebhookPerformance = async (webhookId) => {
  const webhook = await getWebhook(webhookId, { includeEvents: true, eventsLimit: 100 });
  
  const analysis = {
    overall: {
      totalEvents: webhook.delivery_stats.total_events,
      successRate: webhook.delivery_stats.success_rate,
      avgResponseTime: webhook.delivery_stats.average_response_time
    },
    trends: {
      recentFailureRate: (webhook.delivery_stats.last_24h_failures / webhook.delivery_stats.last_24h_events) * 100,
      responseTimeDistribution: analyzeResponseTimes(webhook.recent_events),
      commonErrors: findCommonErrors(webhook.recent_events)
    },
    recommendations: generateRecommendations(webhook)
  };
  
  return analysis;
};

const analyzeResponseTimes = (events) => {
  const times = events.map(e => e.response_time).filter(Boolean);
  return {
    min: Math.min(...times),
    max: Math.max(...times),
    avg: times.reduce((a, b) => a + b, 0) / times.length,
    median: times.sort()[Math.floor(times.length / 2)]
  };
};

​
Best Practices

1

Regular Health Checks

Monitor individual webhook performance and set up alerts for degraded performance.
2

Include Recent Events

Use the include_events parameter to debug delivery issues and understand webhook behavior.
3

Performance Monitoring

Track response times and success rates to identify optimization opportunities.
4

Error Analysis

Analyze recent events to identify patterns in delivery failures and errors.
5

Security Auditing

Regularly review webhook configuration for security best practices.
  • POST /api/v0/webhooks - Create a new webhook
  • GET /api/v0/webhooks - List all webhooks
  • PATCH /api/v0/webhooks/{id} - Update webhook configuration
  • DELETE /api/v0/webhooks/{id} - Delete webhook