webhook-lens MCP server
Commit Nov 6, 2026Inspect, compare, and validate JSON webhook payloads locally using a CLI or MCP server for Claude.
Also known as webizmo/webhook-lens
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 6, 2026
- License
- MIT
What is webhook-lens MCP?
webhook-lens is an MCP server. Inspect, compare, and validate JSON webhook payloads locally using a CLI or MCP server for Claude.
Summary generated from the project's README
About webhook-lens MCP server
Developers who need to analyze JSON webhook changes can use this toolkit to inspect, compare, and validate payloads locally. It functions as both a command-line interface and an MCP server for Claude, allowing you to identify structural drift such as added fields, removed keys, or type changes without setting up a live endpoint. The tool works entirely on local files and does not require API keys or internet connectivity for processing.
When used with Claude, the server provides specific tools like inspect_payload, compare_payloads, and validate_payload to expose structural metadata. You must configure a specific root directory to act as a file-access boundary for your JSON fixtures. This setup ensures the AI only interacts with the specific samples and Draft-07 schemas you provide. For those needing to share data, the CLI includes a redact command to create best-effort copies of files before they are sent to others.
What you can do with it
- 1Detecting structural payload driftCompare two different JSON files to see exactly which fields were added, removed, or had their data types changed.
- 2Analyzing field metadata with ClaudeAsk an AI client to explain the differences between two webhook samples using structural metadata.
- 3Preparing data for sharingCreate a redacted version of a JSON file to remove sensitive information before sharing it.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablewebizmo/webhook-lens is public and reachablegithub.com/webizmo/webhook-lens ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-06github.com/webizmo/webhook-lens ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubWebhook Lens
See what changed in a webhook before you change your integration.
Webhook Lens is a small, local-first JSON inspection toolkit with a CLI and an MCP server for Claude. Compare two payloads, find added or missing fields and type changes, and validate a payload against a JSON Schema—all without setting up a webhook endpoint.
Quick start · Use with Claude · Data boundaries · Türkçe
Why use it?
A provider changes amount from a number to a string. An optional field disappears. A nested object arrives as null. Your integration needs a clear description of the difference before it needs a fix.
Use Webhook Lens to:
- Inspect a sample: understand its field paths, types, and structure.
- Compare samples: spot additions, removals, and type changes.
- Check a contract: validate JSON against a local Draft-07 schema.
- Give Claude structure: expose a restricted fixture directory through MCP, with no raw-value read tool.
- Prepare a redacted copy: run explicit, best-effort redaction from the CLI before sharing a sample.
It works on JSON files you already have. It does not capture live webhooks or replay requests.
Quick start
Requires Node.js 22 or newer and Git. Installation needs access to the npm registry; payload processing runs locally.
git clone https://github.com/webizmo/webhook-lens.git
cd webhook-lens
npm ci
# Try the included sample workflow.
node bin/webhook-lens.js demo
# Inspect field paths and types.
node bin/webhook-lens.js inspect examples/order.created.json
# Compare payload structure.
node bin/webhook-lens.js compare examples/order.created.json examples/order.updated.json
# Validate a payload against a local JSON Schema.
node bin/webhook-lens.js validate examples/order.created.json --schema examples/order.schema.json
The comparison above returns:
{
"added": ["/order/status"],
"removed": ["/customer/phone"],
"typeChanged": [
{ "path": "/order/total", "before": ["number"], "after": ["string"] }
]
}
The examples are synthetic. Start with them before using your own data. All CLI results are JSON; see the CLI reference for exit codes and options, or the verification notes for what has been exercised.
Use with Claude
Add the MCP server to Claude Code using absolute paths:
claude mcp add --transport stdio webhook-lens -- \
node /absolute/path/webhook-lens/bin/webhook-lens.js mcp \
--root /absolute/path/fixtures
Create a dedicated fixture directory containing only the JSON samples and schemas you intend to make available. The root is a file-access boundary, not an operating-system sandbox. Use a trusted directory that a hostile local user cannot modify concurrently, and review the files you place there.
Then ask Claude:
Use Webhook Lens to compare
order.before.jsonandorder.after.json. Explain the added, removed, and type-changed fields, and suggest which integration assumptions I should review.
| MCP tool | Purpose |
|---|---|
inspect_payload(file) |
Return structural metadata for a JSON file. |
compare_payloads(before, after) |
Compare the structure of two JSON files. |
validate_payload(file, schema) |
Check a JSON file against a local Draft-07 schema. |
MCP results contain paths, types, counts, and validation metadata. There is no MCP tool for reading raw payload values or redacting files. Claude still receives the returned metadata: field names and paths can themselves be sensitive.
See the Claude setup guide for configuration, a sample workflow, and troubleshooting.
Redact before sharing
Redaction is an explicit CLI operation. Write a separate output file, then review it:
node bin/webhook-lens.js redact input.json --output redacted.json
The command refuses to overwrite an existing output file. Redaction is best effort; it is not an anonymization guarantee. Sensitive information can appear under unexpected keys or inside free text. Inspect the resulting file before sending it to another person or service.
Data boundaries
- The toolkit processes local JSON; it does not require a hosted account or an API key.
- Payload processing does not send network requests. MCP clients control what they do with returned tool results.
- The MCP server requires an explicit root directory and restricts file access to JSON files under that root.
- JSON Schema validation supports Draft-07. Only same-document schema fragment references such as
#/definitions/orderare supported; other local files and remote schemas are not fetched. - Structural comparisons do not prove that an integration is compatible. A changed value can matter even when the type stays the same.
- Sample inspection cannot prove that every event from a provider follows the same shape.
See security and disclosure for the trust boundaries and reporting guidance.
Useful places to start
| Situation | Try this |
|---|---|
| A webhook handler broke after a provider update | Compare a known-working sample with the new sample. |
| You are writing an integration for a new event | Inspect a sample, then write a schema for the fields your handler needs. |
| You want Claude to help review payload drift | Put reviewed fixtures in a dedicated root and use the MCP tools. |
| You need to share a sample in an issue | Redact a copy, review it manually, and use synthetic data where possible. |
Contribute
Bug reports with small synthetic fixtures are especially useful. See CONTRIBUTING.md for local development and the issue forms to report a bug or suggest an improvement.
If the toolkit helps you, a star makes the project easier to discover. Useful fixtures, clear bug reports, and focused pull requests help it improve.
Built by Webizmo
Webizmo builds websites, business software, and API integrations. We maintain this toolkit to make integration work easier to inspect and discuss.
Need help turning a webhook into a reliable business workflow? Work with Webizmo.
Independent community project; not affiliated with or endorsed by Anthropic. Claude is an Anthropic product.
webhook-lens MCP questions
Can I use this to capture live webhooks?
No, it works on JSON files you already have and does not capture live webhooks or replay requests.
Does the MCP server allow Claude to read raw payload values?
No, there is no MCP tool for reading raw payload values; it only provides structural metadata like paths and types.
Is the redaction feature a guarantee of anonymity?
No, redaction is a best-effort CLI operation and is not an anonymization guarantee.
What version of Node.js is required?
You need Node.js 22 or newer and Git to use the toolkit.