Fetch Webhook

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)

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

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"

curl -X GET "https://api.devdraft.ai/api/v0/webhooks/wh_550e8400e29b41d4a716446655440000?include_events=true&events_limit=20" \
  -H "Content-Type: application/json" \
  -H "x-client-key: your-client-key" \
  -H "x-client-secret: your-client-secret"

const getWebhook = async (webhookId, options = {}) => {
  const { includeEvents = false, eventsLimit = 10 } = options;
  
  const params = new URLSearchParams();
  if (includeEvents) {
    params.append('include_events', 'true');
    params.append('events_limit', eventsLimit.toString());
  }
  
  const url = `https://api.devdraft.ai/api/v0/webhooks/${webhookId}${params.toString() ? '?' + params.toString() : ''}`;

  try {
    const response = await fetch(url, {
      method: 'GET',
      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 fetch webhook: ${response.statusText}`);
    }

    const webhook = await response.json();
    return webhook;
  } catch (error) {
    console.error('Error fetching webhook:', error);
    throw error;
  }
};

// Usage examples
const webhook = await getWebhook('wh_550e8400e29b41d4a716446655440000');
console.log(`Webhook "${webhook.name}" has ${webhook.delivery_stats.success_rate}% success rate`);

// Get webhook with recent events
const webhookWithEvents = await getWebhook(
  'wh_550e8400e29b41d4a716446655440000',
  { includeEvents: true, eventsLimit: 20 }
);
console.log(`Recent events: ${webhookWithEvents.recent_events.length}`);

import requests
from typing import Optional, Dict, Any

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 get_webhook(self, webhook_id: str, include_events: bool = False, events_limit: int = 10) -> Dict[str, Any]:
        headers = {
            'Content-Type': 'application/json',
            'x-client-key': self.client_key,
            'x-client-secret': self.client_secret
        }
        
        params = {}
        if include_events:
            params['include_events'] = 'true'
            params['events_limit'] = str(events_limit)
        
        response = requests.get(
            f"{self.base_url}/api/v0/webhooks/{webhook_id}",
            headers=headers,
            params=params
        )
        
        response.raise_for_status()
        return response.json()
    
    def diagnose_webhook(self, webhook_id: str) -> Dict[str, Any]:
        """Diagnose webhook health and performance"""
        webhook = self.get_webhook(webhook_id, include_events=True, events_limit=50)
        stats = webhook['delivery_stats']
        
        diagnosis = {
            'webhook_id': webhook_id,
            'name': webhook['name'],
            'is_healthy': stats['success_rate'] >= 95,
            'performance_grade': self._get_performance_grade(stats),
            'recommendations': []
        }
        
        # Add recommendations based on stats
        if stats['success_rate'] < 95:
            diagnosis['recommendations'].append('Success rate is below 95% - check endpoint reliability')
        
        if stats['average_response_time'] > 5000:
            diagnosis['recommendations'].append('Response time is high - optimize endpoint performance')
        
        if not webhook['isActive']:
            diagnosis['recommendations'].append('Webhook is inactive - enable if needed')
        
        if not webhook['url'].startswith('https://'):
            diagnosis['recommendations'].append('Use HTTPS for better security')
        
        return diagnosis
    
    def _get_performance_grade(self, stats: Dict[str, Any]) -> str:
        success_rate = stats['success_rate']
        response_time = stats['average_response_time']
        
        if success_rate >= 99 and response_time < 1000:
            return 'A'
        elif success_rate >= 95 and response_time < 3000:
            return 'B'
        elif success_rate >= 90 and response_time < 5000:
            return 'C'
        else:
            return 'D'

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

# Get webhook details
webhook = webhook_manager.get_webhook('wh_550e8400e29b41d4a716446655440000')
print(f"Webhook: {webhook['name']}")
print(f"Success rate: {webhook['delivery_stats']['success_rate']}%")

# Diagnose webhook health
diagnosis = webhook_manager.diagnose_webhook('wh_550e8400e29b41d4a716446655440000')
print(f"Health status: {'Healthy' if diagnosis['is_healthy'] else 'Unhealthy'}")
print(f"Performance grade: {diagnosis['performance_grade']}")

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:read scope"
}

{
  "statusCode": 400,
  "message": "Invalid query parameters",
  "error": "Bad Request",
  "details": "events_limit must be between 1 and 50"
}

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
Performance Issues
Security Concerns

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

Regular Health Checks

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

Include Recent Events

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

Performance Monitoring

Track response times and success rates to identify optimization opportunities.

Error Analysis

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

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

Home

Payment Intents

Webhooks

Wallets

Transfers

Endpoint Details

Authentication

Required Headers

Required Scope

Path Parameters

Query Parameters

Response

Success Response (200 OK)

Response Fields

Webhook Object

Enhanced Delivery Stats

Recent Event Object

Example Requests

Error Responses

Webhook Diagnostics

Health Indicators

Troubleshooting Guide

Use Cases

Webhook Health Monitoring

Performance Analysis

Best Practices

​Endpoint Details

​Authentication

​Required Headers

​Required Scope

​Path Parameters

​Query Parameters

​Response

​Success Response (200 OK)

​Response Fields

​Webhook Object

​Enhanced Delivery Stats

​Recent Event Object

​Example Requests

​Error Responses

​Webhook Diagnostics

​Health Indicators

​Troubleshooting Guide

​Use Cases

​Webhook Health Monitoring

​Performance Analysis

​Best Practices

​Related Endpoints

Endpoint Details

Authentication

Required Headers

Required Scope

Path Parameters

Query Parameters

Response

Success Response (200 OK)

Response Fields

Webhook Object

Enhanced Delivery Stats

Recent Event Object

Example Requests

Error Responses

Webhook Diagnostics

Health Indicators

Troubleshooting Guide

Use Cases

Webhook Health Monitoring

Performance Analysis

Best Practices

Related Endpoints