# Webhook.site MCP server

> Capture and inspect HTTP requests, emails, and DNS lookups to test webhooks, debug API callbacks, and perform security testing.

- Repository: https://github.com/zebbern/webhook-mcp-server
- Page: https://hostedmcp.org/servers/zebbern/webhook-mcp-server
- Transport: stdio
- Stars: 12
- License: MIT
- Latest version: 3.0.0

## Install

### Claude Code

```sh
claude mcp add webhook-mcp-server -- uvx webhook-mcp-server
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "webhook-mcp-server": {
      "command": "uvx",
      "args": [
        "webhook-mcp-server"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

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

### VS Code CLI

```sh
code --add-mcp '{"name":"webhook-mcp-server","type":"stdio","command":"uvx","args":["webhook-mcp-server"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "webhook-mcp-server": {
      "command": "uvx",
      "args": [
        "webhook-mcp-server"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add webhook-mcp-server -- uvx webhook-mcp-server
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.webhook-mcp-server]
command = "uvx"
args = ["webhook-mcp-server"]
```

### Gemini CLI

```sh
gemini mcp add -s user webhook-mcp-server uvx -- webhook-mcp-server
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "webhook-mcp-server": {
      "command": "uvx",
      "args": [
        "webhook-mcp-server"
      ]
    }
  }
}
```

## Tools (31)

- `server_status`: Check this server's setup: API key, account reachability, plan, real-time socket, env config. Call first when a tool fails unexpectedly or before relying on account features. Lists problems in plain words. (read-only)
- `create_webhook`: 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}@emailhook.site), and dns. Next: give the email or URL to the site, then wait_for_email, then follow_email_link or use the OTP. With an API key the URL is permanent (premium) unless WEBHOOK_SITE_DEFAULT_EXPIRY is set; use configure_webhook for custom responses, alias, expiry or request_limit.
- `configure_webhook`: Create a webhook with custom settings, or update one (pass webhook_token). Use when the endpoint should pretend to be an API (status, body, content type, delay up to 30s, CORS), needs an alias, expiry (seconds), a request_limit (0 stores nothing), listen (seconds to wait for update_request response), actions on/off, clone_from another token, a group_id, or a description (label shown in the Control Panel). default_content can be a JSON array of DNS records ([{"type":"a","value":"..."}]) to answer DNSHook lookups. Updates keep every setting you do not mention; alias="" removes the alias. For a plain sign-up inbox use create_webhook.
- `get_webhook_info`: Show a webhook's settings, expiry, request count and every address. Returns url, subdomain_url, force_status_url (append a status code to make the URL answer with it), api_url, email and dns for the token, plus premium / expires_at / alias / request_limit. Use when the user asks if a token is still valid, how it is configured, or needs its callback URL or DNSHook domain. (read-only)
- `get_webhook_email`: Return the temp inbox to sign up, verify, magic-link, or reset a password. Address is {token}@emailhook.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. (read-only)
- `list_webhooks`: List the webhooks (URLs / inboxes) in the account. Needs WEBHOOK_SITE_API_KEY. Use to find an existing token, alias, request count or latest_request_at before creating a new one. Returns pagination. (read-only)
- `delete_webhook`: Permanently delete a webhook and every captured request/email. Use when the user is done with a temp inbox or wants to clean up.
- `get_webhook_requests`: List captured HTTP, email, or DNS events for a webhook, one page at a time. 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_request. To wait for something new use wait_for_request or wait_for_email. Filter emails with request_type='email'. Returns pagination (is_last_page, total) and next_since: pass it back as since to get only what arrived after that call (no paging, no duplicates). (read-only)
- `search_requests`: 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. query uses webhook.site search syntax: 'method:POST', 'content:verify', 'headers.user-agent:curl', 'type:web AND method:POST', '-method:GET' (exclude), '_exists_:custom_action_errors', 'note:todo*', 'country_code:DE', 'created_at:[now-1h TO now]'. Dates are 'yyyy-MM-dd HH:mm:ss' or expressions like now-7d. Returns pagination and next_since (pass back as since for only newer matches). (read-only)
- `get_request`: Return one captured event: the newest by default, or request_id. Set raw=true to also get the untouched body (raw_body). Use for a quick peek; prefer wait_for_email after a sign-up, or get_webhook_requests to see history. (read-only)
- `update_request`: Attach a note to a captured request, or set its dynamic response. response_* call the Set Response API; it only reaches the caller while the request is still held (token listen > 0 with a socket listener; see respond_to_next_request, which does the whole thing). For canned replies use configure_webhook or a modify_response custom action instead.
- `download_request_file`: Download an uploaded file or email attachment (base64) by its file_id. file_id comes from the attachments list on a request or email. (read-only)
- `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. Use to reset an inbox before a new sign-up or test run. date_to='now-7d' deletes everything older than a week.
- `export_webhook_data`: Full dump of captured events with HTML and untruncated bodies, as JSON or CSV. Use when list/wait tools omitted HTML or truncated a body. json pages through up to limit events; csv returns the account's CSV export (paid plans, 3 calls per minute). Filters match search_requests. (read-only)
- `wait_for_request`: Wait until a new HTTP (or DNS) callback hits the webhook (1-120s). Use after giving a site the webhook URL. Listens on webhook.site's socket and falls back to polling. 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. (read-only)
- `wait_for_email`: Wait for a sign-up, verify, magic-link, or password-reset email (1-120s). Call this after the user (or you) submitted {token}@emailhook.site on a website. Returns subject, sender, spam/DKIM checks, a truncated text preview, attachments, 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. (read-only)
- `respond_to_next_request`: Hold the next request that hits the webhook and answer it with your own status, headers and body. Turns the URL into a live mock for one request: the caller waits (up to listen_seconds, max 10) while this tool sets the reply the moment the request arrives over the socket. Use to test a client's retry / error handling ("answer the next call with 500") or to fake an API response on demand; returns the captured request. For a fixed canned reply use configure_webhook instead.
- `follow_email_link`: Open the verify / magic-link / reset URL from a captured sign-up email. Use after wait_for_email. Opens the best-ranked auth link; pass request_id (the email's uuid) to pick a specific email, or url to open another link from that email. Only follows http(s) links already in the inbox, to public hosts unless the server's FOLLOW_EMAIL_LINK_ALLOW_HOSTS allows more. Returns status, final URL, page preview, the ranked auth_links, and blocked_redirect if a redirect was refused after the link itself succeeded. For OTP codes, read verification_codes from wait_for_email.
- `manage_custom_actions`: Manage the Custom Actions webhook.site runs on every request or email a token receives. action: types (reference of all 63 action types; pass type= for one type's parameters, live-verified status and example) | variables ($request.*$ variables and modifiers) | script_reference (every WebhookScript function with its signature, for type=script) | list | create | update | delete | test | execute. create/update take type (modify_response, http, script, javascript, send_email, extract_jsonpath, conditions, rate_limit, log, set_variable, mock, ...) with parameters, order, and optionally name (label), queue/delay/ condition (id of a conditions action) and queue_id (a Queue Profile from manage_queues). test dry-runs the given action against request_id without changing saved actions; execute re-runs all saved actions on request_id. Actions also fire on incoming emails, so guard email-sending actions with a condition on $request.type$. Never point http/send_request at a webhook.site URL (recursion is disabled).
- `manage_schedules`: Manage Schedules: webhook.site calls request_url on an interval (needs API key). action: list | get | create | update | delete | run | logs. interval is monthly, weekly, daily, hourly, 10-minute, 5-minute, 1-minute or cron (then set cron, e.g. '*/5 * * * *'). request_headers are newline separated. require_* raise an error notification when the response does not match; require_cert_expiry alerts when the HTTPS certificate expires in fewer than that many days. Use for uptime checks or periodic cleanup calls (e.g. DELETE .../token/{id}/request?date_to=now-7d with Api-Key).
- `manage_global_variables`: Manage Global Variables shared by all URLs, usable as $name$ in Custom Actions and Schedules. action: list | create | update | delete. Needs API key.
- `manage_groups`: Manage Groups that organise the account's webhooks (needs API key). action: list | create | update | delete. Assign a token to a group with configure_webhook(group_id=...).
- `manage_queues`: Manage Queue Profiles that throttle queued Custom Actions (needs API key). action: list | create | update | delete. A profile allows `amount` jobs every `duration` seconds, drops jobs not run within `expiry` seconds, and waits `delay` seconds before the first run. Attach it to an action with manage_custom_actions(queue=true, queue_id=...).
- `manage_templates`: Manage Templates: reusable sets of Custom Actions plus predefined variables (needs API key). action: list | create | update | delete. actions is a list of action objects (type, order, parameters...); variables is a list of {name, value}. Include a template in a token with a 'template' action.
- `manage_databases`: Manage webhook.site Databases and run SQL against them (needs API key). action: list | create | update | delete | query. create needs name and plan. query runs SQL with optional positional (?) or named (:name) params and returns up to 1000 rows.
- `manage_users`: Manage team users on an Enterprise account (needs an administrator API key). action: list | invite | update | delete. user_type_id: 100 admin, 200 member, 300 viewer.
- `generate_oob_payloads`: Build authorized out-of-band payloads that ping this webhook: SSRF URLs, XSS callbacks, or canary tokens. Use only on systems you are allowed to test — not for sign-up email. kind='ssrf' (include_dns/include_ip), 'xss' (include_cookies/include_dom), 'canary' (canary_type url|dns|email: a tripwire, not an inbox). Confirm hits with check_for_callbacks. (read-only)
- `check_for_callbacks`: See if SSRF, XSS, or canary callbacks arrived in the last N minutes. Use after generate_oob_payloads. For a website verification email, use wait_for_email. (read-only)
- `extract_links_from_request`: Pull confirm, reset, magic-link, and other URLs from a captured email or HTTP body. Use after wait_for_email or get_webhook_requests when the user needs the verification / login / password-reset link or OTP. Defaults to the latest event. wait_for_email already extracts links and codes. (read-only)
- `send_requests`: Send one JSON body (data) or several (payloads) to the webhook URL to test capture. Use when the user wants to send sample payloads or load-test, not when they are waiting for a real site or email. Any HTTP method; delay_ms spaces out multiple payloads.

## FAQ

### How can I use this for security testing?

You can generate SSRF payloads, XSS callback payloads, and canary tokens to detect blind vulnerabilities or unauthorized access.

### Do I need an account to use the server?

No, everything works without an account using anonymous 7-day URLs, but an API key unlocks permanent URLs and advanced account features.
