Fetch Webhook

Retrieve detailed information about a specific webhook endpoint

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

Parameter	Type	Description	Required
webhook_id	string	Unique identifier for webhook	Yes

Query Parameters

Parameter	Type	Description	Default	Example
include_events	boolean	Include recent delivery events	false	?include_events=true
events_limit	integer	Number of recent events to include (1-50)	10	?events_limit=20

Response

Success Response (200 OK)

Response

{
  "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

Field	Type	Description
id	string	Unique identifier for the webhook
name	string	Human-readable name for the webhook
url	string	Endpoint URL where events are sent
isActive	boolean	Whether the webhook is currently active
encrypted	boolean	Whether payloads are encrypted
signing_secret	string	Secret used for signature verification
created_at	string	ISO 8601 timestamp when webhook was created
updated_at	string	ISO 8601 timestamp when webhook was last updated
delivery_stats	object	Detailed statistics about webhook deliveries
app	object	Application information
recent_events	array	Recent delivery events (if requested)

Enhanced Delivery Stats

Field	Type	Description
total_events	number	Total number of events sent to this webhook
successful_deliveries	number	Number of successfully delivered events
failed_deliveries	number	Number of failed delivery attempts
last_delivery	string	ISO 8601 timestamp of last delivery attempt
success_rate	number	Delivery success rate percentage
average_response_time	number	Average response time in milliseconds
last_24h_events	number	Events sent in the last 24 hours
last_24h_failures	number	Failed deliveries in the last 24 hours

Recent Event Object

Field	Type	Description
id	string	Unique identifier for the delivery event
event_type	string	Type of event that was delivered
delivery_status	string	Status of delivery (delivered, failed, pending)
response_code	number	HTTP response code from webhook endpoint
response_time	number	Response time in milliseconds
error_message	string	Error message (if delivery failed)
created_at	string	When the event was created
delivered_at	string	When delivery was attempted
retry_count	number	Number of retry attempts

Example Requests

Basic Request

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

404 Not Found

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

Webhook Diagnostics

Health Indicators

Success Rate

• Excellent: 99%+ success rate
• Good: 95-99% success rate
• Warning: 90-95% success rate
• Critical: Below 90% success rate

Response Time

• 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

Recent Activity

• Active: Events delivered in the last 24 hours
• Idle: No events in the last 24 hours
• Failing: Multiple failures in recent deliveries

Troubleshooting Guide

Delivery Failures

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

Performance Issues

Optimization strategies:

• Async processing: Process events asynchronously in webhook handler
• Quick responses: Return HTTP 200 immediately, process later
• Error handling: Implement proper error handling and logging
• Rate limiting: Implement rate limiting on webhook endpoint

Security Concerns

Security best practices:

• Signature verification: Always verify webhook signatures
• HTTPS only: Use HTTPS endpoints for all webhooks
• IP whitelisting: Consider IP whitelisting for sensitive webhooks
• Payload encryption: Enable encryption for sensitive data

Use Cases

Webhook Health Monitoring

Health Monitoring Dashboard

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

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.

Related Endpoints

• 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