​
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

​
webhookId
string
Filter events by webhook ID (e.g., “wh_123”)
​
status
string
Filter by event status
  • success - Successfully processed events
  • failed - Failed events
  • pending - Events waiting to be processed
​
limit
number
default:100
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

​
webhookId
string
Filter requests by webhook ID
​
eventId
string
Filter requests by event ID
​
status
string
Filter by request status
  • success - Successful requests (2xx status codes)
  • failed - Failed requests (4xx, 5xx status codes)
  • timeout - Timed out requests
​
limit
number
default:100
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

​
eventId
string
required
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

​
requestId
string
required
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

​
webhookId
string
Get stats for specific webhook (omit for all webhooks)
​
timeRange
string
default:"24h"
Time range for statistics
  • 1h - Last hour
  • 24h - Last 24 hours
  • 7d - Last 7 days
  • 30d - 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

CodeDescription
INVALID_PARAMETERInvalid parameter value
NOT_FOUNDResource not found
PERMISSION_DENIEDNo access to resource
RATE_LIMITEDToo many requests
INTERNAL_ERRORServer error

​
Best Practices

  1. Use filters effectively - Always filter by webhookId when debugging specific integrations
  2. Limit results - Start with smaller limits and increase if needed
  3. Check error details - The analysis tools provide actionable recommendations
  4. Monitor stats regularly - Use get_webhook_stats to track webhook health
  5. 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