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

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

See Resource Reference for data schemas
Check Integration Examples for common workflows
Review MCP Overview for protocol details

​MCP Tools Reference

​search_events

​Parameters

​Response

​Example Usage

​search_requests

​Parameters

​Response

​Example Usage

​analyze_event

​Parameters

​Response

​Example Usage

​analyze_request

​Parameters

​Response

​Example Usage

​get_webhook_stats

​Parameters

​Response

​Example Usage

​Error Handling

​Common Error Codes

​Best Practices

​Rate Limits

​Next Steps

MCP Tools Reference

search_events

Parameters

Response

Example Usage

search_requests

Parameters

Response

Example Usage

analyze_event

Parameters

Response

Example Usage

analyze_request

Parameters

Response

Example Usage

get_webhook_stats

Parameters

Response

Example Usage

Error Handling

Common Error Codes

Best Practices

Rate Limits

Next Steps