Using AI Agents to Debug Webhooks with MCP

AI coding agents write webhook handlers, but they can't test them. They generate the code, tell you "this should work," and move on. If the handler breaks in production, you debug it yourself.

The webhooks.cc MCP server changes this. It gives agents direct access to webhook testing: create endpoints, send signed payloads, inspect captures, verify signatures, and replay requests — all from within the agent's tool loop.

One-command setup

The MCP server reads your API key from the WHK_API_KEY environment variable. Install it for your editor or agent:

claude mcp add -s user --transport stdio webhooks-cc \
  -e WHK_API_KEY=whcc_... -- npx -y @webhooks-cc/mcp

Or add the config manually to your MCP settings file:

{
  "mcpServers": {
    "webhooks-cc": {
      "command": "npx",
      "args": ["-y", "@webhooks-cc/mcp"],
      "env": {
        "WHK_API_KEY": "whcc_..."
      }
    }
  }
}

Get your API key at webhooks.cc/account.

What the server exposes

The MCP server provides 25 tools, 3 prompts, and 3 resource surfaces.

Tools by category

Endpoints — create, list, get, update, delete endpoints, plus batch variants (create_endpoints, delete_endpoints).

Requests — list, search, count, get, and clear captured requests. Wait for one (wait_for_request) or many (wait_for_requests). Replay, compare, and extract fields from captures.

Send and test — send_webhook sends a signed provider payload through a hosted endpoint. send_to sends directly to any URL. preview_webhook shows the exact request that would be sent without sending it. test_webhook_flow runs the full cycle — create, send, capture, verify, replay, cleanup — in a single tool call.

Discovery — list_provider_templates shows available providers and their event templates. get_usage checks quota. describe returns a self-description of all available operations.

Prompts

The server exposes three MCP prompts that give agents structured starting points:

• debug_webhook_delivery — diagnose why a webhook isn't arriving
• setup_provider_testing — configure endpoint and signing for a specific provider
• compare_webhook_attempts — diff two captured requests

These prompts don't execute anything. They provide context and a step-by-step plan the agent follows using the tools above.

Resources

Three MCP resources provide webhook context without tool calls:

• webhooks://endpoints — list of current endpoints
• webhooks://endpoint/{slug}/recent — recent requests for an endpoint
• webhooks://request/{id} — full details of a single request

Agents that support resource browsing can attach these as context before starting work.

Example: debug a failing Stripe handler

Here's what an agent session looks like with the MCP server connected:

You: My Stripe webhook handler returns 400. Debug it.
 
Agent: I'll create a test endpoint and send a signed Stripe
       checkout event to see what your handler receives.
 
       [create_endpoint] → https://go.webhooks.cc/w/xyz789
       [send_webhook provider="stripe"
        template="checkout.session.completed"
        secret="whsec_test"] → sent
 
       [wait_for_request slug="xyz789" timeout="15s"]
       → captured: POST, 247 bytes, stripe-signature header present
 
       [extract_from_request id="req_abc" fields=["body.type"]]
       → "checkout.session.completed"
 
       The webhook arrived correctly. Let me check your handler code...
 
       [reads handler file, finds JSON parse error on line 42]
 
       Your handler calls JSON.parse on the raw body before
       express.raw() processes it. Remove the manual parse —
       req.body is already a Buffer when using express.raw().

The agent used four MCP tools to create the endpoint, send a signed payload, capture the request, and extract the event type. It found the bug without you leaving your editor.

Example: one-shot flow test

For quick verification, test_webhook_flow runs the entire cycle in a single tool call:

You: Test that my GitHub webhook handler verifies signatures correctly.
 
Agent: [test_webhook_flow
        provider="github"
        template="push"
        secret="github_secret"
        targetUrl="http://localhost:3000/webhooks/github"]
       → endpoint created, webhook sent, request captured,
         signature verified (valid), replayed to localhost:3000,
         endpoint cleaned up
 
       Your handler accepted the signed GitHub push event
       and returned 200.

Supported providers

The MCP server generates signed payloads for eight webhook providers:

Discord is supported for signature verification but not payload generation.

Use list_provider_templates to see every available template with its signature header and signing requirements.

Embed the server programmatically

If you're building your own agent or tool chain, import the server directly:

import { createServer } from "@webhooks-cc/mcp";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
const server = createServer({
  apiKey: process.env.WHK_API_KEY!,
});
 
await server.connect(new StdioServerTransport());

registerTools(), registerPrompts(), and registerResources() are also exported if you want to attach webhooks.cc capabilities to an existing MCP server.

FAQ