Agentic Webhook Testing with MCP

AI coding assistants are great at writing code. They're not so great at verifying that code works against real external services. Webhook integrations are a particularly painful example — the assistant can write a handler, but it can't trigger a Stripe payment, wait for the webhook, and confirm the handler actually processed it.

CatchHook's MCP server bridges that gap. It gives your AI assistant 20 tools to work with your webhook endpoints directly: create endpoints, wait for traffic, inspect payloads, diagnose failures, compare events, and more. The debugging loop that used to involve bouncing between your editor, CatchHook's dashboard, and Stripe's dashboard can happen entirely in conversation.

Setup

1. Create an API Token

Go to Account Settings → API Tokens in CatchHook. Create a token with both read and write scopes.

2. Configure Your Editor

Claude Code:

claude mcp add catchhook --transport http \
  --url https://catchhook.app/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "catchhook": {
      "url": "https://catchhook.app/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Windsurf — add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "catchhook": {
      "serverUrl": "https://catchhook.app/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Codex CLI:

export CATCHHOOK_TOKEN="YOUR_TOKEN"
codex mcp add catchhook --url https://catchhook.app/mcp \
  --bearer-token-env-var CATCHHOOK_TOKEN

Workflow: Building a Stripe Webhook Handler

Here's what an end-to-end agentic workflow looks like. Each step is just a natural language request to your assistant.

Step 1: Create an Endpoint

Create a CatchHook endpoint called stripe-checkout-dev

The assistant calls create_endpoint and returns the webhook URL. Paste this into Stripe's webhook settings.

Step 2: Wait for Traffic

Wait for the next Stripe checkout.session.completed event on that endpoint

The assistant calls wait_for_request with the provider and event type filters. It blocks until a matching webhook arrives (up to 30 seconds), then shows the full payload with provider context.

While it's waiting, go trigger the event — complete a checkout flow in Stripe's test mode.

Step 3: Inspect the Payload

Show me the full request details

The assistant calls get_request and shows headers, body, provider detection, event type, and signature status. Now you both know exactly what data the handler needs to work with.

Step 4: Write the Handler

Write a Rails controller action to handle this Stripe checkout event

The assistant has seen the real payload. It writes a handler that matches the actual data shape — not a guess from Stripe's documentation examples.

Step 5: Diagnose Issues

Diagnose request req_abc123

The assistant calls diagnose_request and gets back signature verification status, provider setup checks, and recommended next steps. If the signing secret isn't configured, it'll tell you. If the signature format is wrong, it explains why.

Step 6: Compare Events

Compare this checkout event with the previous one

The assistant calls compare_requests with both request IDs. The diff highlights provider-aware differences — not just raw JSON changes, but semantic ones like "amount changed from $20 to $50" or "customer ID is different."

Step 7: Test Locally via Tunnel

For actually getting the webhook to your local server, you'll want to start the CatchHook tunnel in a separate terminal:

npx @catchhook/tunnel start --provider stripe --port 3000

Then ask your assistant to send a test request or wait for the next event. The tunnel handles delivery to localhost — the MCP tools handle the inspection, diagnosis, and comparison from within your editor.

Step 8: Verify and Iterate

Wait for the next checkout event and diagnose it

The assistant chains wait_for_request and diagnose_request. You trigger another checkout in Stripe, and the assistant confirms the webhook arrived, checks signature status, and flags anything unusual. If your handler returns a 500, you can inspect what went wrong without leaving the editor.

Available MCP Tools

Endpoint Management

Request Inspection

Agentic Workflow

Replay and Forwarding

Analysis and Diagnostics

Alerts

Tips for Effective Agentic Testing

Be specific about what you want

"Wait for the next Stripe invoice.paid event" works way better than "wait for something." The filters on wait_for_request narrow the search so you're not sifting through noise.

Use compare for regression testing

After changing your handler, trigger the same event type again and compare the two requests. The diff tells you whether the provider sent different data or your handler is just responding differently to the same input.

Diagnose before reading code

When a webhook handler fails, the instinct is to read the code. But if the signature is failing because the secret isn't configured, no amount of code reading will find that. Ask the assistant to diagnose the request first — it'll save you the trip.

Pair MCP tools with the tunnel

MCP tools are great for inspection, diagnosis, and comparison from within your editor. The tunnel is what actually gets webhooks to your local server. Use them together: tunnel for delivery, MCP for understanding what was delivered and whether your handler got it right.

Authentication and Security

MCP tokens use the same API token system as CatchHook's REST API. Tokens require:

• read scope for inspection and listing tools
• write scope for creating endpoints, replaying, and managing actions

Tokens are account-scoped — the assistant can only access your endpoints and requests. Create and manage tokens in Account Settings → API Tokens.