Hookwarden — Webhook Integrity

[hookwarden]

The first MCP server doing webhook signature verification.
Local. Deterministic. Zero network. JS / TS / Python / PHP / Go — 27 providers — 3-state verdicts.

[npm version] [License: Apache 2.0] [Node 22+] [MCP spec 2025-06-18]

What it does

@hookwarden/mcp exposes hookwarden's deterministic webhook-verification engine as MCP tools. AI coding agents — Claude Desktop, Cursor, Continue, and apps built on the Anthropic Agent SDK — get two tools:

• scan_handler — scan pasted webhook handler code and get back a structured finding (verified / not-verified / manual-review) for Stripe, GitHub, Shopify, Twilio, and 23 other providers.
• verify_audit_chain — verify a hookwarden evidence pack's hash chain + KMS-signed Merkle roots offline (no network, no auth), returning { valid, broken_at_row, signatures_verified }.

Runs entirely client-side. Zero network egress from the MCP process. Zero auth. The same engine the hookwarden CLI ships — same rule pack, same content hashes, end-to-end provenance.

Install in one command

npx @hookwarden/mcp init

That command detects your installed MCP clients (Claude Desktop / Cursor / Continue), prints a per-OS summary table, and writes the canonical config to each one. .bak files land alongside every config it touches. Restart the relevant client and scan_handler + verify_audit_chain appear in the tool list.

Pass --all for non-interactive use, --dry-run to preview, --force to overwrite an existing mcpServers.hookwarden entry, or --clients claude-desktop,cursor to limit the set.

Manual configuration

If you'd rather not run the init helper, write the config by hand.

Claude Desktop

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

{  "mcpServers": {    "hookwarden": {      "command": "npx",      "args": ["-y", "@hookwarden/mcp"]    }  }}

Cursor

~/.cursor/mcp.json — same shape as Claude Desktop:

{  "mcpServers": {    "hookwarden": {      "command": "npx",      "args": ["-y", "@hookwarden/mcp"]    }  }}

Continue.dev

Continue uses a per-server file. Write ~/.continue/mcpServers/hookwarden.yaml:

name: hookwardencommand: npxargs: [-y, "@hookwarden/mcp"]

Anthropic Agent SDK

The Agent SDK is programmatic — there's no config file to edit. Drop this into your code:

import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({  prompt: "Audit this webhook handler for missing signature verification...",  options: {    mcpServers: {      hookwarden: {        command: "npx",        args: ["-y", "@hookwarden/mcp"],      },    },  },})) {  console.log(message);}

The init helper does not write here — the SDK integration is code, not config.

The scan_handler tool

Inputs

Output

Returns Tool.result with structuredContent first-class (MCP spec 2025-06-18) plus a companion stringified-JSON text block for backwards compatibility:

{  "verdict_summary": { "verified": 0, "not_verified": 1, "manual_review": 0, "parse_error": 0 },  "findings": [    {      "rule_id": "stripe/missing-signature-verification",      "provider": "stripe",      "severity": "critical",      "verdict": "not-verified",      "file": "__handler.ts",      "line_start": 7,      "line_end": 9,      "message": "Webhook handler reads req.body without calling stripe.webhooks.constructEvent...",      "provider_docs_url": "https://stripe.com/docs/webhooks",      "references": [        "https://www.svix.com/blog/common-failure-modes-for-webhook-signatures/",        "https://hookdeck.com/webhooks/guides/webhook-security-vulnerabilities-guide"      ],      "rule_pack_version": "0.7.2"    }  ],  "scan_metadata": {    "engine_version": "0.7.2",    "rule_pack_version": "0.7.2",    "rule_pack_content_hash": "938f7565e29f19e0cbd34594731d1de2b0ffd40ee87aacaa8be2435fc1f47f32"  }}

Verdict vocabulary

Same 3-state vocabulary as the CLI. No remapping in the MCP layer.

Error payloads (isError: true)

Parse failures don't crash the transport — they emit as rule_id: "engine/parse-error" findings with severity high and increment verdict_summary.parse_error.

The verify_audit_chain tool

Verify a hookwarden evidence pack's integrity offline — no network, no AWS, no credentials. "Verify the chain without trusting hookwarden." The tool walks the per-row hash chain, roundtrips the manifest hash, and — for v1.1 packs that embed the signing CMK's SPKI public key — verifies the ECDSA-P256 (MessageType:DIGEST) Merkle-root + manifest signatures with node:crypto.

Inputs

Output

{  "valid": true,  "broken_at_row": null,  "signatures_verified": 2}

Trust model

The v1.1 pack carries its own SPKI public key. The signature proves the pack was not altered after signing by the holder of that key — it is trust-on-first-use. To pin trust to a specific signer out-of-band, an auditor can cross-check signature.signing_cmk_arn against AWS KMS GetPublicKey and confirm the embedded SPKI key matches. Malformed pack JSON returns isError: true (error: "invalid_pack_json") — the tool never throws past its boundary.

This tool imports only @hookwarden/canonical-json (the shared RFC 8785 byte-equality anchor) + node:crypto. It does not load the engine or rule pack and does not run the drift gate.

Integrity claims

• Zero outbound TCP — the published tarball passes pnpm inspect-bundle, a structural CI gate that rejects any source-file import of HTTP clients (node:http, axios, undici, etc.) and any direct dependency outside the documented allowlist.
• Drift detection — every scan_handler call cross-checks the runtime-resolved engine + rule-pack hashes against the build-time dist/build-manifest.json. Mismatch returns isError: true with structured engine_drift / rules_drift payload. No env-var opt-out. See drift-detection — including the v0.8.0 engine-content-hash limitation.
• No telemetry — the tarball declares no analytics or tracking SDKs (@datadog/*, @segment/*, @sentry/*, etc.) in dependencies or transitively in source-file imports.
• Open source — Apache-2.0 at Hookwarden/hookwarden/packages/mcp/. Engine + rule pack land in the same monorepo and ship under the same license.

Links

• Documentation — getting started, tool surface reference, drift detection
• npm package
• GitHub repository
• Apache-2.0 License

Copyright 2026 Hookwarden contributors. Apache License 2.0.