Metadata-Version: 2.5
Name: webhook-mcp-server
Version: 2.2.2
Summary: MCP Server for webhook.site API integration with layered architecture
Project-URL: Repository, https://github.com/zebbern/webhook-mcp-server
Project-URL: Homepage, https://github.com/zebbern/webhook-mcp-server
Author-email: zebbern <zebbern@users.noreply.github.com>
License: MIT
License-File: LICENSE
Keywords: api-testing,bugbounty,mcp,model-context-protocol,testing,webhook
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Requires-Dist: mcp>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=1.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.22.0; extra == 'dev'
Requires-Dist: tiktoken>=0.7.0; extra == 'dev'
Description-Content-Type: text/markdown

# Webhook.site MCP Server

[![PyPI](https://img.shields.io/pypi/v/webhook-mcp-server.svg)](https://pypi.org/project/webhook-mcp-server/)
[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-24%20tools-brightgreen.svg)](https://modelcontextprotocol.io/)

A Model Context Protocol (MCP) server for [webhook.site](https://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](#quick-start)
- [What Can You Do?](#what-can-you-do)
- [Tools Reference](#tools-reference)
- [Examples](#examples)
- [Each Webhook Token Provides](#each-webhook-token-provides)
- [Architecture](#architecture)
- [Development](#development)
- [Contributing](#contributing)
- [Requirements](#requirements)
- [Changelog](#changelog)
- [Credits](#credits)
- [Links](#links)

---

## Quick Start

### Installation

```bash
# Using uvx (recommended - no install needed)
uvx webhook-mcp-server==2.2.2

# Or install via pip
pip install webhook-mcp-server==2.2.2
```

Use `2.2.2` or newer. `2.1.3` does not start on MCP 2.0.

### VS Code / GitHub Copilot

Add to `.vscode/mcp.json`:

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

### Cursor

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

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

### Claude Desktop

Add to `claude_desktop_config.json`:

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

---

## 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"
```

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

### Creative/Practical:

```
"Create a webhook that pretends to be a Stripe payment API"
"Make a fake login endpoint that captures credentials (for pentesting)"
"Set up an email inbox that auto-extracts verification codes"
```

<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

### Webhook Management

| Tool                         | Description                                        |
| ---------------------------- | -------------------------------------------------- |
| `create_webhook`             | Start here: disposable URL, temp email, and DNS for sign-up or callbacks |
| `create_webhook_with_config` | Create with custom response, status, CORS, timeout |
| `get_webhook_url`            | Get the full URL for a webhook token               |
| `get_webhook_email`          | Temp inbox `{token}@email.webhook.site` for sign-up / verify / magic-link / reset |
| `get_webhook_dns`            | Get the DNS subdomain for a webhook                |
| `get_webhook_info`           | Get webhook settings and statistics                |
| `update_webhook`             | Modify webhook configuration                       |
| `delete_webhook`             | Delete a webhook endpoint                          |

### Request Handling

| Tool                   | Description                                 |
| ---------------------- | ------------------------------------------- |
| `send_to_webhook`      | Send JSON data to a webhook                 |
| `get_webhook_requests` | List all captured requests                  |
| `search_requests`      | Search with filters (method, content, date) |
| `get_latest_request`   | Get the most recent captured request        |
| `delete_request`       | Delete a specific request                   |
| `delete_all_requests`  | Bulk delete with filters                    |

### Real-Time Waiting

| Tool               | Description                                   |
| ------------------ | --------------------------------------------- |
| `wait_for_request` | Wait for a **new** HTTP request (polling, 1-120s). Set `return_existing` to reuse old traffic. |
| `wait_for_email`   | After sign-up: wait for verify / magic-link / reset mail, links, and OTP codes |
| `follow_email_link` | Open a captured verify / magic / reset URL and return the page preview |

### Bug Bounty / Security

| Tool                         | Description                                          |
| ---------------------------- | ---------------------------------------------------- |
| `generate_ssrf_payload`      | Create SSRF test payloads (HTTP, DNS, IP-based)      |
| `generate_xss_callback`      | Create XSS callback payloads with cookie/DOM capture |
| `generate_canary_token`      | Create trackable URLs, DNS, or email canaries        |
| `check_for_callbacks`        | Quick check for OOB callbacks                        |
| `extract_links_from_request` | Pull confirm / reset / magic-link URLs from a captured email or HTTP body |

### Batch & Utility

| Tool                     | Description                             |
| ------------------------ | --------------------------------------- |
| `send_multiple_requests` | Send batch of requests for load testing |
| `export_webhook_data`    | Export all requests to JSON             |

---

## Examples

### Sign up on a website

1. `create_webhook` — get `email` (`{token}@email.webhook.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

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

### Wait for Password Reset Email

```json
// 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"]
}
```

### SSRF Testing Payload

```json
// Response from generate_ssrf_payload
{
  "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 |
| **Subdomain** | `https://{token}.webhook.site` | Alternative URL format      |
| **Email**     | `{token}@email.webhook.site`   | Capture incoming emails     |
| **DNS**       | `{token}.dnshook.site`         | Capture DNS lookups         |

---

## Architecture

```
webhook-mcp-server/
├── server.py              # MCPServer entry point + lifespan
├── handlers/              # Typed @mcp.tool() registrations
├── services/              # Business logic
│   ├── webhook_service.py # Webhook CRUD
│   ├── request_service.py # Request management
│   └── bugbounty_service.py # Security payloads
├── models/                # Config / filter / result types
└── utils/                 # HTTP client, logging, validation
```

### Key Features

- **Async Architecture** - Non-blocking I/O for optimal performance
- **Retry Logic** - Exponential backoff for transient failures
- **Input Validation** - UUID validation, parameter sanitization
- **Structured Logging** - JSON logs for debugging and monitoring
- **Type Safety** - Full type hints throughout

---

## Development

### Setup

```bash
git clone https://github.com/zebbern/webhook-mcp-server.git
cd webhook-mcp-server
pip install -e ".[dev]"
```

### Run Tests

```bash
# Offline unit tests (default for CI)
pytest -m "not live" -v

# Live webhook.site tests
pytest -m live -v
```

### Run Locally

```bash
python server.py
```

---

## Requirements

- Python 3.10+
- `mcp >= 2.0.0`
- `httpx >= 0.25.0`

---

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history.

---

## Contributing

Contributions are welcome! Here's how you can help:

1. **Report bugs** - Open an issue describing the problem
2. **Suggest features** - Open an issue with your idea
3. **Submit PRs** - Fork the repo and submit a pull request

### Development Setup

```bash
git clone https://github.com/zebbern/webhook-mcp-server.git
cd webhook-mcp-server
pip install -e ".[dev]"
pytest -m "not live" -v
```

### Guidelines

- Follow existing code style
- Add tests for new features
- Update documentation as needed
- Keep PRs focused on a single change

---

## Credits
- [Simon Fredsted (Founder of webhook.site)](https://github.com/fredsted)
- [Official webhook.site open source repo](https://github.com/webhooksite/webhook.site)

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

## Links

- 📦 [PyPI Package](https://pypi.org/project/webhook-mcp-server/)
- 🐙 [GitHub Repository](https://github.com/zebbern/webhook-mcp-server)
- 🌐 [webhook.site](https://webhook.site) - The service this MCP wraps
- 📖 [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification


---

**Made with ❤️ for the MCP community**
