Skip to main content
Glama
Webhook.site MCP Server

Webhook.site MCP Server

by zebbern

Webhook.site MCP Server

PyPI Python MCP

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.

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


Table of Contents


Related MCP server: hookray-mcp

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"

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"

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)

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"

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"

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"

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'"

Canary Tokens

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

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.

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.

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

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


Made with ❤️ for the MCP community

Available Tools

24 tools
check_for_callbacksA

See if SSRF, XSS, or canary callbacks arrived in the last N minutes.

    Use after generate_ssrf_payload / generate_xss_callback / generate_canary_token.
    For a website verification email, use wait_for_email.
    

Inputs: webhook_token (required), identifier, since_minutes. Returns: object

create_webhookA

Create a disposable inbox to sign up on a website: HTTP URL, temp email, DNS.

    Use this first when the user wants to sign up, receive a verification /
    magic-link / password-reset email, catch a webhook callback, or get a
    one-off URL. Returns token, url, email ({token}@email.webhook.site),
    and dns. Next: give the email or URL to the site, then wait_for_email,
    then follow_email_link or use the OTP.
    

Inputs: no named parameters. Returns: object

create_webhook_with_configA

Create a webhook that returns a custom status, body, timeout, CORS, or alias.

    Use when the user wants the endpoint to pretend to be an API (404, delay,
    JSON body) instead of a default 200. For a normal sign-up inbox, use
    create_webhook.
    

Inputs: cors, alias, expiry, timeout, +3 more. Returns: object

delete_all_requestsB

Clear captured events on a webhook, optionally by date or search query.

Use to reset an inbox before a new sign-up or test run.

Inputs: webhook_token (required), query, date_to, date_from. Returns: object

delete_requestA

Delete one captured HTTP, email, or DNS event by request id.

Inputs: request_id (required), webhook_token (required). Returns: object

delete_webhookA

Permanently delete a webhook and every captured request/email.

Use when the user is done with a temp inbox or wants to clean up.

Inputs: webhook_token (required). Returns: object

export_webhook_dataA

Full dump of captured HTTP/email/DNS events, including HTML and untruncated bodies.

Use this when list/wait tools omitted HTML or truncated a body.

Inputs: webhook_token (required), limit. Returns: object

generate_canary_tokenA

Make a canary URL, DNS name, or email that alerts when someone opens it.

    Use to mark your own files or systems. token_type='email' is a tripwire,
    not a sign-up inbox — use create_webhook + wait_for_email for that.
    

Inputs: webhook_token (required), identifier, token_type. Returns: object

generate_ssrf_payloadB

Build authorized SSRF callback URLs that ping this webhook.

    Use only on systems you are allowed to test — not for sign-up email.
    Confirm hits with check_for_callbacks. local_bypass_examples cannot
    be confirmed here.
    

Inputs: webhook_token (required), identifier, include_ip, include_dns. Returns: object

generate_xss_callbackA

Build authorized XSS payloads that ping this webhook when they run.

    Use only on systems you are allowed to test. Confirm with check_for_callbacks.
    

Inputs: webhook_token (required), identifier, include_dom, include_cookies. Returns: object

get_latest_requestA

Return only the newest captured event (HTTP, email, or DNS).

    Use for a quick peek. Prefer wait_for_email after a sign-up, or
    get_webhook_requests to see history.
    

Inputs: webhook_token (required). Returns: object

get_webhook_dnsA

Return the DNSHook domain for an existing webhook.

    Use for out-of-band DNS callbacks, not for sign-up email. create_webhook
    already returns dns.
    

Inputs: webhook_token (required), validate. Returns: object

get_webhook_emailA

Return the temp inbox to sign up, verify, magic-link, or reset a password.

    Address is {token}@email.webhook.site. Use when the user already has a
    token. If they do not, call create_webhook first — it also returns
    email. After the site sends mail, call wait_for_email.
    

Inputs: webhook_token (required), validate. Returns: object

get_webhook_infoA

Show webhook settings, expiry, and how many requests it has received.

Use when the user asks if a token is still valid or how it is configured.

Inputs: webhook_token (required). Returns: object

get_webhook_requestsA

List captured HTTP, email, or DNS events for a webhook.

    Use to inspect what already arrived. Bodies are truncated and HTML is
    omitted; use export_webhook_data for the full dump. For the newest item
    use get_latest_request. To wait for something new use wait_for_request
    or wait_for_email. Filter emails with request_type='email'.
    

Inputs: webhook_token (required), limit, request_type. Returns: object

get_webhook_urlA

Return https://webhook.site/{token} for an existing webhook.

    Use when the user already has a token and needs the HTTP callback URL.
    For a new inbox, create_webhook already returns url.
    

Inputs: webhook_token (required), validate. Returns: object

search_requestsA

Search captured events by method, body text, headers, type, or date.

    Use when the user asks to find POSTs, a keyword, or only emails/DNS.
    Examples: query='method:POST', query='content:verify', request_type='email'.
    

Inputs: webhook_token (required), limit, query, date_to, +3 more. Returns: object

send_multiple_requestsA

POST several sample JSON payloads to the webhook, optionally spaced out.

Use to load-test capture, not to wait for a real site or email.

Inputs: payloads (required), webhook_token (required), delay_ms. Returns: object

send_to_webhookA

POST JSON to the webhook URL to test that capture works.

Use when the user wants to send a sample payload, not when they are waiting for a real site or email.

Inputs: data (required), webhook_token (required), headers. Returns: object

update_webhookB

Change how an existing webhook responds (status, body, timeout, CORS).

    Use after create_webhook when the user wants a different canned reply.
    

Inputs: webhook_token (required), cors, timeout, default_status, +2 more. Returns: object

wait_for_emailA

Wait for a sign-up, verify, magic-link, or password-reset email (1-120s).

    Call this after the user (or you) submitted {token}@email.webhook.site
    on a website. Returns subject, a truncated text preview, extracted
    confirm / reset / login URLs, and verification_codes (OTP). Next:
    follow_email_link, or type the code. HTML is omitted; use
    export_webhook_data for the full message. Set return_existing=true if
    the email already arrived. If there is no token yet, create_webhook first.
    

Inputs: webhook_token (required), extract_links, return_existing, timeout_seconds. Returns: object

wait_for_requestA

Poll until a new HTTP (or DNS) callback hits the webhook (1-120s).

    Use after giving a site the webhook URL. Bodies are truncated and HTML
    is omitted; use export_webhook_data for the full dump. For verification
    / magic-link / password-reset mail, use wait_for_email instead. Set
    return_existing=true if the request may already be there.
    

Inputs: webhook_token (required), request_type, return_existing, timeout_seconds. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 24 tools

    Disambiguation5/5

    Every tool has a clearly defined purpose with explicit guidance on when to use it. Overlaps like get_latest_request vs get_webhook_requests are disambiguated in descriptions, and security tools are separate from email/webhook tools.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in snake_case (e.g., create_webhook, delete_request, wait_for_email). Security payload generators use generate_ prefix, and check_for_callbacks fits the pattern. No mixed conventions.

    Tool Count4/5

    24 tools is on the higher side but justified by the broad scope: webhook lifecycle, email capture, DNS, request management, and security testing. Each tool earns its place, though some could theoretically be merged without much loss.

    Completeness5/5

    The surface covers the full lifecycle: create, configure, send, retrieve, wait, export, update, delete, search, and security payload generation. No obvious gaps for the stated purpose of webhook testing and temporary inbox functionality.

    Maintenance

    ActivityStale
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables generating webhook endpoints for testing, inspecting and comparing HTTP request payloads, replaying requests from history, and forwarding requests to localhost.
      2
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to create disposable webhook URLs, capture incoming HTTP requests, inspect headers and bodies, and replay them against local or remote endpoints, streamlining the webhook handler development loop.
      5
      6 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables management and inspection of webhook tokens (URLs) and incoming requests via webhook-test.com, allowing users to create, list, fetch details, fetch payloads, and delete webhooks without custom API integrations.
      -