Webhook.site MCP Server MCP Server

Webhook.site MCP Server

A Model Context Protocol (MCP) server for webhook.site - instantly capture HTTP requests, emails, and DNS lookups. Perfect for testing webhooks, debugging API callbacks, security testing, and bug bounty hunting.

<!-- mcp-name: io.github.zebbern/webhook-mcp-server -->

Security helper tools (SSRF, XSS, canary tokens) are for authorized testing only — systems you own or have explicit permission to test.

---

Table of Contents

• Quick Start
• What Can You Do?
• Tools Reference
• Examples
• Each Webhook Token Provides
• Documentation
• Development
• Requirements
• Contributing
• Credits
• Links

---

Quick Start

Installation

# Using uvx (recommended - no install needed)
uvx webhook-mcp-server==3.0.0

# Or install via pip
pip install webhook-mcp-server==3.0.0

Use 3.0.0 or newer. 2.1.3 does not start on MCP 2.0; 3.0 renames a few tools (see Upgrading from 2.x).

VS Code / GitHub Copilot

Add to .vscode/mcp.json:

{
  "servers": {
    "webhook-mcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": ["webhook-mcp-server==3.0.0"]
    }
  }
}

Cursor

Add to .cursor/mcp.json (project) or your user MCP config:

{
  "mcpServers": {
    "webhook-mcp-server": {
      "command": "uvx",
      "args": ["webhook-mcp-server==3.0.0"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "webhook-mcp-server": {
      "command": "uvx",
      "args": ["webhook-mcp-server==3.0.0"]
    }
  }
}

Configuration

All settings are environment variables on the server process. Put them in the env block of your MCP client config.

Variable	Purpose
WEBHOOK_SITE_API_KEY	Your webhook.site API key. Makes new URLs permanent (your plan's quota) and unlocks list_webhooks, Custom Actions, Schedules, Global Variables, Groups, Queue Profiles, Templates, Databases, Users and CSV export
WEBHOOK_SITE_DEFAULT_EXPIRY	Seconds until new URLs expire when the call does not pass expiry. Unset means permanent on a paid account (7 days for anonymous URLs)
WEBHOOK_MCP_RATE_LIMIT_MAX_WAIT	When webhook.site answers 429 with a Retry-After up to this many seconds (default 15), the call waits and retries once; longer waits are reported as an error naming the wait
FOLLOW_EMAIL_LINK_ALLOW_HOSTS	follow_email_link only opens links to public internet hosts, and connects to the address it checked (no DNS rebinding). To test a sign-up flow on your own machine or intranet, list what to allow: localhost,127.0.0.1,*.corp.example,10.0.0.0/8
HTTPS_PROXY / HTTP_PROXY / NO_PROXY	Honoured by follow_email_link. The proxy makes the connection, so the target is checked before the request instead of being pinned
SSL_CERT_FILE / SSL_CERT_DIR	Custom CA bundle for follow_email_link, for corporate TLS interception

If the request to a verification link completes and then redirects somewhere that is not allowed (a local dev server, an intranet dashboard), the tool reports that hop's status with the refused target in blocked_redirect instead of failing: the request that consumed the token already went through, whether or not the site counted it as verified.

---

What Can You Do?

Capture Webhooks

"Create a webhook and show me the URL"
"What requests have been sent to my webhook?"
"Wait for a request to come in"

<img width="555" height="555" alt="Webhooks" src="https://github.com/user-attachments/assets/75558234-9d93-4b79-817e-373a5ce75382" />

Security/Bug Bounty:

"Generate an SSRF payload to test for blind vulnerabilities"
"Create XSS callback payloads to detect blind XSS attacks"
"Make me a canary token to detect if someone accesses a URL"

<img width="555" height="555" alt="Security" src="https://github.com/user-attachments/assets/12150308-932a-4872-acd9-5473c7dde6ff" />

Email Automation:

"Create a temp email and wait for a password reset link"
"Monitor this webhook for emails and extract all links from them"
"Give me 3 temporary emails at once" (batch creation)

<img width="555" height="555" alt="Email" src="https://github.com/user-attachments/assets/04af7d6e-e8aa-4e35-a817-2204cde8f5e7" />

API Testing:

"Create a webhook that returns a 404 error with a custom message"
"Make a webhook with CORS enabled that waits 5 seconds before responding"
"Send 10 different test requests to a webhook and show me all the captured data"
"Hold the next request and answer it with a 402 and this JSON body"

<img width="555" height="555" alt="API" src="https://github.com/user-attachments/assets/d8f2c46b-fb40-4e57-8957-0edef8e94db6" />

Real-time Monitoring:

"Create a webhook and wait for any HTTP request to arrive"
"Monitor for DNS lookups to detect if a server is making DNS queries"
"Search all requests for ones containing 'password' in the body"

<img width="555" height="555" alt="Monitoring" src="https://github.com/user-attachments/assets/12c9d270-f9df-489a-8be1-9afb4726404b" />

Data Analysis:

"Export all captured webhook requests to JSON format"
"Show me statistics on requests received in the last hour"
"Filter and show only POST requests with specific headers"

<img width="555" height="555" alt="Data" src="https://github.com/user-attachments/assets/51cd0032-d92b-46e7-9f0c-6cee96b6e4f3" />

Automate with your account:

"Add a Custom Action that forwards every request to my staging API"
"Schedule a health check of https://example.com every 5 minutes and alert on a bad status"
"Write a WebhookScript that answers with the request's JSON field 'id'"

<img width="555" height="555" alt="Practical" src="https://github.com/user-attachments/assets/a15bcbc4-087a-40bb-a1e5-a42475bd1301" />

Canary Tokens

"Create a canary URL to track document access"
"Generate a DNS canary for the config file"
"Set up an email tracker pixel"

<img width="555" height="555" alt="CanaryTokens" src="https://github.com/user-attachments/assets/2e6af1f5-55d6-4670-b899-6809f3031439" />

---

Tools Reference

Everything works without an account on anonymous 7-day URLs. With WEBHOOK_SITE_API_KEY set, URLs are permanent and the account tools unlock the features of your plan. Every webhook_token accepts the UUID, an alias, a pasted https://webhook.site/... URL or the inbox address. Full parameters for each tool: docs/TOOLS.md.

<!-- tools:start -->

31 tools, generated from the server by scripts/gen_tool_docs.py.

Diagnostics

Tool	What it does
server_status	Check this server's setup: API key, account reachability, plan, real-time socket, env config.

Webhooks

Tool	What it does
create_webhook	Create a disposable inbox to sign up on a website: HTTP URL, temp email, DNS.
configure_webhook	Create a webhook with custom settings, or update one (pass webhook_token).
get_webhook_info	Show a webhook's settings, expiry, request count and every address.
get_webhook_email	Return the temp inbox to sign up, verify, magic-link, or reset a password.
list_webhooks	List the webhooks (URLs / inboxes) in the account. Needs WEBHOOK_SITE_API_KEY.
delete_webhook	Permanently delete a webhook and every captured request/email.

Requests

Tool	What it does
send_requests	Send one JSON body (data) or several (payloads) to the webhook URL to test capture.
get_webhook_requests	List captured HTTP, email, or DNS events for a webhook, one page at a time.
search_requests	Search captured events by method, body text, headers, type, or date.
get_request	Return one captured event: the newest by default, or request_id.
update_request	Attach a note to a captured request, or set its dynamic response.
download_request_file	Download an uploaded file or email attachment (base64) by its file_id.
delete_request	Delete one captured HTTP, email, or DNS event by request id.
delete_all_requests	Clear captured events on a webhook, optionally by date or search query.
export_webhook_data	Full dump of captured events with HTML and untruncated bodies, as JSON or CSV.

Real-time

Tool	What it does
wait_for_request	Wait until a new HTTP (or DNS) callback hits the webhook (1-120s).
wait_for_email	Wait for a sign-up, verify, magic-link, or password-reset email (1-120s).
respond_to_next_request	Hold the next request that hits the webhook and answer it with your own status, headers and body.
follow_email_link	Open the verify / magic-link / reset URL from a captured sign-up email.

Account features (API key)

Tool	What it does
manage_custom_actions	Manage the Custom Actions webhook.site runs on every request or email a token receives.
manage_schedules	Manage Schedules: webhook.site calls request_url on an interval (needs API key).
manage_global_variables	Manage Global Variables shared by all URLs, usable as $name$ in Custom Actions and Schedules.
manage_groups	Manage Groups that organise the account's webhooks (needs API key).
manage_queues	Manage Queue Profiles that throttle queued Custom Actions (needs API key).
manage_templates	Manage Templates: reusable sets of Custom Actions plus predefined variables (needs API key).
manage_databases	Manage webhook.site Databases and run SQL against them (needs API key).
manage_users	Manage team users on an Enterprise account (needs an administrator API key).

Security testing

Tool	What it does
generate_oob_payloads	Build authorized out-of-band payloads that ping this webhook: SSRF URLs, XSS callbacks, or canary tokens.
check_for_callbacks	See if SSRF, XSS, or canary callbacks arrived in the last N minutes.
extract_links_from_request	Pull confirm, reset, magic-link, and other URLs from a captured email or HTTP body.

<!-- tools:end -->

Upgrading from 2.x

2.x tool	3.0 replacement
create_webhook_with_config, update_webhook	configure_webhook (pass webhook_token to update)
get_webhook_url, get_webhook_dns	fields of get_webhook_info
get_latest_request	get_request
send_to_webhook, send_multiple_requests	send_requests (data or payloads)
generate_ssrf_payload, generate_xss_callback, generate_canary_token	generate_oob_payloads (kind=ssrf|xss|canary, canary_type)

---

Examples

Sign up on a website

1. create_webhook — get email ({token}@emailhook.site)
2. Use that address on the site (sign-up, verify, magic link, or password reset)
3. wait_for_email — receive the message, confirm / login / reset URLs, and any OTP
4. follow_email_link to open a verify link, or type verification_codes on the site

If you already have a token, get_webhook_email returns the same inbox.

Create a Webhook

// Response from create_webhook
{
  "token": "abc123-def456-...",
  "url": "https://webhook.site/abc123-def456-...",
  "email": "abc123-def456-...@emailhook.site",
  "dns": "abc123-def456-....dnshook.site"
}

Wait for Password Reset Email

// Response from wait_for_email
{
  "email_received": true,
  "subject": "Password Reset Request",
  "from": "noreply@example.com",
  "auth_links": ["https://example.com/reset?token=xyz789"],
  "verification_codes": ["847291"]
}

Poll for new events without paging

// get_webhook_requests(webhook_token, since=<next_since from the previous call>)
{
  "requests": [ ... only what arrived after the cursor ... ],
  "next_since": 1788472548944304
}

SSRF Testing Payload

// Response from generate_oob_payloads(kind="ssrf")
{
  "payloads": {
    "http": "https://webhook.site/token?id=ssrf-test",
    "dns": "ssrf-test.token.dnshook.site",
    "ip_decimal": "http://2130706433/token",
    "ip_hex": "http://0x7f000001/token"
  }
}

---

Each Webhook Token Provides

Endpoint	Format	Use Case
HTTP URL	https://webhook.site/{token}	Capture HTTP/HTTPS requests (any sub-path too)
Subdomain	https://{token}.webhook.site	Alternative URL format
Forced status	https://webhook.site/{token}/{status}	Answer with that status, for retry-logic tests
Email	{token}@emailhook.site	Capture incoming emails
DNS	{token}.dnshook.site	Capture DNS lookups (every subdomain)

---

Documentation

Page	Contents
docs/TOOLS.md	Every tool with parameters and hints, generated from the server
docs/webhook-site-notes.md	What webhook.site actually does, verified live, including where the official docs are wrong
docs/testing.md	The four test layers, recordings, verification scripts, model evals, account safety
docs/releasing.md	Version bumps, tagging, the publish workflow
CHANGELOG.md	Version history

---

Development

git clone https://github.com/zebbern/webhook-mcp-server.git
cd webhook-mcp-server
pip install -e ".[dev]"
pytest -m "not live and not live_auth"     # offline suite incl. replay of recorded live exchanges
python server.py                            # run the server on stdio

The offline suite replays real recorded webhook.site exchanges; the live tool check and the live / live_auth tiers hit the real API. Details in docs/testing.md.

Layout: server.py (entry point and lifespan), handlers/tools.py (tool registrations), services/ (one module per API area), utils/ (HTTP client, real-time socket, URL safety, references), scripts/ (live check, generators, verifiers), evals/ (model-in-the-loop prompts).

---

Requirements

• Python 3.10+
• mcp >= 2.0.0
• httpx >= 0.26.0, httpcore >= 1.0.0, anyio >= 4.0.0
• python-socketio[asyncio_client] >= 5.11.0 (real-time waiting; the tools fall back to polling without it)

---

Contributing

Bug reports and PRs are welcome. Keep a PR to one change, add a test whose expectation was checked against the real API (see docs/testing.md), and run python scripts/gen_tool_docs.py after touching a tool.

---

Credits

• Simon Fredsted (Founder of webhook.site)
• Official webhook.site open source repo

This project is not affiliated with or endorsed by webhook.site

Links

• 📦 PyPI Package
• 🐙 GitHub Repository
• 🌐 webhook.site - The service this MCP wraps
• 📖 Model Context Protocol - MCP specification

---

Made with ❤️ for the MCP community