Webhook Toolkit

webhook-toolkit

Receive, forward, sign and verify webhooks from your terminal, your test suite and your AI agent. One package: a CLI (webhook-toolkit, alias whtk), a typed library and an MCP server, backed by webhook-toolkit.com.

Quick start

npx webhook-toolkit listen --forward http://localhost:3000/webhooks

That's it: no account, no config. You get a public URL; paste it into Stripe, GitHub, Shopify or any other sender, and every webhook shows up in your terminal and is re-sent to your local handler:

  webhook-toolkit · listening

Webhook URL https://webhook-toolkit.com/r/l90c9MKIdo0o Inspector https://webhook-toolkit.com/e/l90c9MKIdo0o Forwarding → http://localhost:3000/webhooks Expires in 7 days (2026-09-25 15:42) Anonymous URL. Run webhook-toolkit login to get a permanent one.

Waiting for webhooks. Ctrl+C to stop.

15:42:11 POST /stripe stripe checkout.session.completed 248 B ↳ 200 OK · 3 ms 15:42:11 POST /github github push 269 B ↳ 500 Internal Server Error · 1 ms {"error":"handler crashed: cannot read properties of undefined"}

Every request is also kept in a web inspector (headers, raw body, replay), so nothing is lost when your handler crashes.

Contents

• CLI
• Test webhooks in your test suite
• Use it from AI agents (MCP)
• Signing and verifying
• Relay: a real tunnel (paid)
• Free vs paid
• How it compares
• Library reference
• Configuration

CLI

npm i -g webhook-toolkit     # or run any command with npx webhook-toolkit …

A few things worth knowing:

• Sub-paths and query strings are kept. A request to …/r/ /stripe?x=1 is forwarded to http://localhost:3000/webhooks/stripe?x=1, so one URL can feed several handlers.
• Headers are forwarded as received (minus hop-by-hop headers, host and content-length), so signature checks in your handler pass exactly as in production.
• `--json` prints NDJSON (listening, request, forward events) for scripting: whtk listen -f 3000 --json | jq .request.event.
• Colors follow NO_COLOR, FORCE_COLOR and are off when output is not a terminal.

Send a signed test event

# Prints the headers and a curl command, with a realistic sample event

whtk sign stripe --secret whsec_… --event checkout.session.completed

Or send it straight to your handler

whtk sign github --secret my-secret --file push.json --send http://localhost:3000/api/github whtk sign twilio --secret --url https://example.com/sms --send 3000

Debug "invalid signature"

whtk verify stripe --secret whsec_test_secret --body-file body.json \

-H "Stripe-Signature: t=1726000000,v1=a530ce3d81556a0eced506e1d1cad777bc55bc1e408e54dd6bfef08e1dde216c"

✗ Invalid Stripe signature (body_trailing_newline_added) The signature matches the body without its trailing newline: a newline was appended after signing (proxy, logger, copy-paste). Verify the raw bytes exactly as received. expected t=1726000000,v1=1e0085bf1054f89ac8882e2e5fcbfdf301b1d6445e8ed7a316120cd5dc651ba9 received t=1726000000,v1=a530ce3d81556a0eced506e1d1cad777bc55bc1e408e54dd6bfef08e1dde216c timestamp 1726000000 (738 days ago)

The verifier replays the usual mistakes (whitespace in the secret, added or stripped trailing newline, CRLF conversion, expired timestamp, and for Twilio: http vs https, port, query string, trailing slash, repeated parameters) and tells you which one matches. The same logic powers the online signature validator.

Test webhooks in your test suite

The library gives your tests a real public URL and a way to wait for what lands on it. It works anonymously; set WEBHOOK_TOOLKIT_KEY in CI for permanent URLs and higher limits.

Vitest (or Jest in ESM mode)

import { expect, test } from "vitest";

import { WebhookToolkit, verify } from "webhook-toolkit";

const wt = new WebhookToolkit(); // anonymous, or reads WEBHOOK_TOOLKIT_KEY

test("creating an order notifies the customer's webhook", async () => { const endpoint = await wt.createEndpoint({ name: "ci-orders" });

// The app under test sends its outgoing webhooks to the capture URL. await api.post("/settings/webhooks", { url: endpoint.url, secret: "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw" }); await api.post("/orders", { sku: "tshirt", quantity: 2 });

const req = await wt.waitForRequest(endpoint.token, { timeoutMs: 30_000, filter: (r) => JSON.parse(r.body).type === "order.created", });

expect(JSON.parse(req.body).data.quantity).toBe(2); // Your outgoing signatures are correct, too: expect(verify("svix", { secret: "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw", rawBody: req.body, headers: req.headers }).valid).toBe(true); });

waitForRequest checks requests that already arrived since the endpoint was created, then long-polls until timeoutMs, so the order of "trigger" and "wait" does not matter. It rejects with a WebhookToolkitError (code: "timeout") when nothing matched.

To test your handler without any network at all, sign the payload locally:

import { sign } from "webhook-toolkit";

const { headers, body } = sign("stripe", { secret: process.env.STRIPE_WEBHOOK_SECRET!, event: "checkout.session.completed" }); const res = await fetch("http://localhost:3000/api/webhooks/stripe", { method: "POST", headers, body }); expect(res.status).toBe(200);

Playwright

import { expect, test } from "@playwright/test";

import { WebhookToolkit } from "webhook-toolkit";

const wt = new WebhookToolkit();

test("'Send test event' reaches the configured URL", async ({ page }) => { const endpoint = await wt.createEndpoint();

await page.goto("/settings/integrations"); await page.getByLabel("Webhook URL").fill(endpoint.url); await page.getByRole("button", { name: "Save" }).click(); await page.getByRole("button", { name: "Send test event" }).click();

const req = await wt.waitForRequest(endpoint.token, { timeoutMs: 15_000 }); expect(req.method).toBe("POST"); expect(req.headers["content-type"]).toContain("application/json"); });

The package is ESM-only. CommonJS test runners work on Node ≥ 20.19 / 22.12 (native require(esm)); Jest needs its ESM mode.

Use it from AI agents (MCP)

webhook-toolkit mcp is a Model Context Protocol server. Your coding agent can create a webhook URL, wait for the delivery after triggering it, read the payload, then replay it or send freshly signed events to your localhost handler while it fixes the code.

The API key is optional: everything except list_webhook_urls and explain_webhook_request works anonymously.

Claude Code

claude mcp add webhook-toolkit -- npx -y webhook-toolkit mcp

with a key:

claude mcp add webhook-toolkit --env WEBHOOK_TOOLKIT_KEY=whk_… -- npx -y webhook-toolkit mcp

Cursor (.cursor/mcp.json), Windsurf (~/.codeium/windsurf/mcp_config.json), Claude Desktop (claude_desktop_config.json)

{

"mcpServers": { "webhook-toolkit": { "command": "npx", "args": ["-y", "webhook-toolkit", "mcp"], "env": { "WEBHOOK_TOOLKIT_KEY": "whk_…" } } } }

VS Code (.vscode/mcp.json)

{

"inputs": [ { "type": "promptString", "id": "webhook-toolkit-key", "description": "webhook-toolkit.com API key (optional)", "password": true } ], "servers": { "webhook-toolkit": { "type": "stdio", "command": "npx", "args": ["-y", "webhook-toolkit", "mcp"], "env": { "WEBHOOK_TOOLKIT_KEY": "${input:webhook-toolkit-key}" } } } }

Codex CLI (~/.codex/config.toml)

[mcp_servers.webhook-toolkit]

command = "npx" args = ["-y", "webhook-toolkit", "mcp"] env = { WEBHOOK_TOOLKIT_KEY = "whk_…" }

ChatGPT, Claude.ai and other remote-capable clients: add a custom connector pointing at the hosted server, nothing to install:

https://webhook-toolkit.com/mcp

(Streamable HTTP, optional Authorization: Bearer whk_….) The hosted server cannot reach your machine, so replaying to localhost and send_signed_webhook need the local server above.

Outputs are compact text plus the key JSON; bodies over 20 KB are truncated with a note pointing to the inspector. To embed the server in your own process: import { createMcpServer } from "webhook-toolkit/mcp".

Signing and verifying

sign() and verify() run locally with node:crypto: secrets never leave your machine. Signatures are byte-for-byte identical to the webhook-toolkit.com signer, and the tests check them against the providers' published examples (GitHub, Slack, Twilio, Svix).

| Shopify | shopify | X-Shopify-Hmac-Sha256 | HMAC-SHA256 base64 of the body | app client se