Documentation Index
Fetch the complete documentation index at: https://docs.unhook.sh/llms.txt
Use this file to discover all available pages before exploring further.
MCP Tools Reference
Tools allow AI assistants to perform actions and queries on your webhook data. Each tool has specific parameters and returns structured data.
search_events
Search and filter webhook events based on various criteria.
Parameters
Filter events by webhook ID (e.g., “wh_123”)
Filter by event status
success - Successfully processed eventsfailed - Failed eventspending - Events waiting to be processed
Maximum number of events to return (1-100)
Response
{
"events": [
{
"id": "evt_123",
"webhookId": "wh_456",
"status": "failed",
"createdAt": "2024-01-15T10:30:00Z",
"provider": "stripe",
"eventType": "payment_intent.succeeded",
"error": "Connection timeout",
"retryCount": 3
}
],
"total": 42,
"hasMore": true
}
Example Usage
{
"name": "search_events",
"arguments": {
"webhookId": "wh_stripe_prod",
"status": "failed",
"limit": 50
}
}
search_requests
Search webhook requests with filtering options.
Parameters
Filter requests by webhook ID
Filter requests by event ID
Filter by request status
success - Successful requests (2xx status codes)failed - Failed requests (4xx, 5xx status codes)timeout - Timed out requests
Maximum number of requests to return (1-100)
Response
{
"requests": [
{
"id": "req_789",
"eventId": "evt_123",
"webhookId": "wh_456",
"status": "failed",
"statusCode": 500,
"duration": 1523,
"createdAt": "2024-01-15T10:30:05Z",
"method": "POST",
"url": "https://api.example.com/webhook",
"headers": {
"content-type": "application/json",
"x-stripe-signature": "..."
},
"error": "Internal server error"
}
],
"total": 156,
"hasMore": true
}
Example Usage
{
"name": "search_requests",
"arguments": {
"eventId": "evt_123",
"status": "failed"
}
}
analyze_event
Get detailed analysis of a specific webhook event.
Parameters
The ID of the event to analyze
Response
{
"event": {
"id": "evt_123",
"webhookId": "wh_456",
"status": "failed",
"createdAt": "2024-01-15T10:30:00Z",
"provider": "stripe",
"eventType": "payment_intent.succeeded"
},
"requests": [
{
"id": "req_789",
"status": "failed",
"statusCode": 500,
"duration": 1523,
"createdAt": "2024-01-15T10:30:05Z"
}
],
"payload": {
"id": "pi_123",
"object": "payment_intent",
"amount": 1000,
"currency": "usd"
},
"analysis": {
"failureReason": "Target endpoint returned 500 error",
"retryable": true,
"recommendations": [
"Check target endpoint health",
"Review server logs for errors",
"Consider implementing retry logic"
]
}
}
Example Usage
{
"name": "analyze_event",
"arguments": {
"eventId": "evt_123"
}
}
analyze_request
Get detailed analysis of a specific webhook request.
Parameters
The ID of the request to analyze
Response
{
"request": {
"id": "req_789",
"eventId": "evt_123",
"webhookId": "wh_456",
"status": "failed",
"statusCode": 500,
"duration": 1523,
"createdAt": "2024-01-15T10:30:05Z",
"method": "POST",
"url": "https://api.example.com/webhook"
},
"requestHeaders": {
"content-type": "application/json",
"x-stripe-signature": "...",
"user-agent": "Stripe/1.0"
},
"requestBody": {
"id": "pi_123",
"object": "payment_intent",
"amount": 1000
},
"responseHeaders": {
"content-type": "text/html",
"server": "nginx/1.19.0"
},
"responseBody": "<html><body>Internal Server Error</body></html>",
"analysis": {
"issue": "Endpoint returned HTML error page instead of JSON",
"possibleCauses": [
"Application crashed",
"Misconfigured error handling",
"Database connection failure"
],
"recommendations": [
"Check application logs",
"Verify webhook endpoint configuration",
"Test endpoint manually with curl"
]
}
}
Example Usage
{
"name": "analyze_request",
"arguments": {
"requestId": "req_789"
}
}
get_webhook_stats
Get comprehensive statistics for webhooks.
Parameters
Get stats for specific webhook (omit for all webhooks)
Time range for statistics
1h - Last hour24h - Last 24 hours7d - Last 7 days30d - Last 30 days
Response
{
"summary": {
"totalEvents": 1523,
"successfulEvents": 1456,
"failedEvents": 67,
"successRate": 0.956,
"averageResponseTime": 245
},
"webhooks": [
{
"id": "wh_456",
"name": "Stripe Production",
"provider": "stripe",
"stats": {
"totalEvents": 892,
"successfulEvents": 875,
"failedEvents": 17,
"successRate": 0.981,
"averageResponseTime": 198
}
}
],
"eventTypes": [
{
"type": "payment_intent.succeeded",
"count": 456,
"successRate": 0.993,
"averageResponseTime": 167
}
],
"errorDistribution": [
{
"error": "Connection timeout",
"count": 23,
"percentage": 0.343
},
{
"error": "500 Internal Server Error",
"count": 19,
"percentage": 0.284
}
],
"timeSeriesData": {
"labels": ["2024-01-14T00:00:00Z", "2024-01-14T01:00:00Z"],
"successful": [45, 52],
"failed": [2, 1]
}
}
Example Usage
{
"name": "get_webhook_stats",
"arguments": {
"webhookId": "wh_stripe_prod",
"timeRange": "7d"
}
}
Error Handling
All tools return errors in a consistent format:
{
"error": {
"code": "INVALID_PARAMETER",
"message": "Invalid webhook ID format",
"details": {
"parameter": "webhookId",
"value": "invalid",
"expected": "Format: wh_xxx"
}
}
}
Common Error Codes
| Code | Description |
|---|
INVALID_PARAMETER | Invalid parameter value |
NOT_FOUND | Resource not found |
PERMISSION_DENIED | No access to resource |
RATE_LIMITED | Too many requests |
INTERNAL_ERROR | Server error |
Best Practices
- Use filters effectively - Always filter by webhookId when debugging specific integrations
- Limit results - Start with smaller limits and increase if needed
- Check error details - The analysis tools provide actionable recommendations
- Monitor stats regularly - Use get_webhook_stats to track webhook health
- Combine tools - Use search tools to find issues, then analyze tools for details
Rate Limits
Tools are subject to the following limits:
- Maximum 60 tool calls per minute
- Maximum result size of 1MB per call
- Search results capped at 100 items
Next Steps
