The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Webhook Toolkit listing page.
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.
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:
Every request is also kept in a web inspector (headers, raw body, replay), so nothing is lost when your handler crashes.
| Command | What it does |
|---|---|
whtk listen [--forward <url>] | Public URL + live stream of incoming requests, optionally re-sent to localhost. Reuses your last URL while it is alive (--new for a fresh one). |
whtk relay --to <url|port> | Real tunnel: callers get your local app's response. Paid. |
whtk sign <provider> --secret <s> | Build a validly signed webhook: prints headers + a ready-to-run curl, or sends it with --send. |
whtk verify <provider> --secret <s> … | Check a signature, and when it fails, say why. |
whtk replay <token> <id> --to <url> | Re-send a captured request from your machine (localhost works). |
whtk requests <token> | List captured requests (--json for scripts). |
whtk endpoints | List your account's URLs. |
whtk login / logout / whoami | Save, remove or inspect your API key. |
whtk mcp | Start the MCP server on stdio. |
A few things worth knowing:
…/r/<token>/stripe?x=1 is forwarded to http://localhost:3000/webhooks/stripe?x=1, so one URL can feed several handlers.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.NO_COLOR, FORCE_COLOR and are off when output is not a terminal.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.
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.
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:
The package is ESM-only. CommonJS test runners work on Node ≥ 20.19 / 22.12 (native
require(esm)); Jest needs its ESM mode.
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
Cursor (.cursor/mcp.json), Windsurf (~/.codeium/windsurf/mcp_config.json), Claude Desktop (claude_desktop_config.json)
VS Code (.vscode/mcp.json)
Codex CLI (~/.codex/config.toml)
ChatGPT, Claude.ai and other remote-capable clients: add a custom connector pointing at the hosted server, nothing to install:
(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.
| Tool | Use it to |
|---|---|
create_webhook_url | Get a public URL to receive a webhook from a third-party service or the app under test |
wait_for_webhook | Block until the delivery arrives (filters: provider, event, method, path, body); safe to call after triggering |
list_webhook_requests / get_webhook_request | See what was actually sent: headers, raw body, detected provider and event |
replay_webhook_request | Re-send a captured request from the local machine to e.g. http://localhost:3000/api/webhooks |
send_signed_webhook | POST a validly signed event (Stripe, GitHub, Shopify, Slack, Twilio, Mailgun, Svix, Paddle, Discord) to your handler |
sign_webhook_payload | Compute signature headers and a curl command without sending |
verify_webhook_signature | Explain why a handler rejects a signature |
set_webhook_response | Change what the URL answers (status, body): simulate failures, answer challenges |
list_webhook_urls | Find an existing permanent URL (key required) |
explain_webhook_request | AI explanation of a payload, or a generated handler (paid, 3 free trials) |
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".
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).
| Provider | id | Signature | Algorithm | secret |
|---|---|---|---|---|
| Stripe | stripe | Stripe-Signature | HMAC-SHA256 hex of t.body | endpoint secret whsec_… |
| GitHub, Gitea, Forgejo | github | X-Hub-Signature-256 (+ X-Hub-Signature) | HMAC-SHA256 hex of the body | webhook secret |
| Shopify | shopify | X-Shopify-Hmac-Sha256 | HMAC-SHA256 base64 of the body | app client secret |
| Slack | slack | X-Slack-Signature, X-Slack-Request-Timestamp | HMAC-SHA256 hex of v0:ts:body | signing secret |
| Twilio | twilio | X-Twilio-Signature | HMAC-SHA1 base64 of URL + sorted params (bodySHA256 for JSON) | auth token, plus url |
| Mailgun | mailgun | signature object in the body | HMAC-SHA256 hex of timestamp + token | webhook signing key |
| Svix / Standard Webhooks (Clerk, Resend) | svix | svix-* and webhook-* headers | HMAC-SHA256 base64 of id.ts.body | whsec_… |
| Paddle Billing | paddle | Paddle-Signature | HMAC-SHA256 hex of ts:body | pdl_ntfset_… |
| Discord interactions | discord | X-Signature-Ed25519, X-Signature-Timestamp | Ed25519 | verify: app public key; sign: a test private key |
verify() returns { valid, reason?, message, expected?, received?, timestamp? }. Failure reasons: missing_signature, malformed_signature, missing_timestamp, missing_url, invalid_secret, timestamp_out_of_tolerance (default 300 s, toleranceSeconds: 0 disables), signature_mismatch, secret_whitespace, body_trailing_newline_added, body_trailing_newline_removed, body_line_endings_changed, url_mismatch (Twilio), body_hash_mismatch (Twilio JSON). Comparisons are constant-time.
detectProvider(headers, body) returns { provider, event } from a data-driven table (DETECTION_RULES), for example { provider: "stripe", event: "invoice.paid" } or { provider: "twilio", event: "message.received" }. It knows Stripe, GitHub, GitLab, Bitbucket, Shopify, WooCommerce, Slack, SendGrid, Twilio, Paddle, Svix (Clerk, Resend), GoCardless, PayPal, Discord, Linear, Typeform, Calendly, Square, HubSpot, Zoom, Lemon Squeezy, Coinbase Commerce, Twitch, Mux, Vercel, Netlify, Sentry, Trello, Plaid, Mandrill, Jira, Postmark, Mollie, Adyen, Mailgun and Redsys. Adding one is a table entry plus a test fixture.
listen --forward is free and fine for most webhooks, but the sender receives the capture URL's response, not your app's. When the sender needs your real answer (Slack slash commands, Twilio TwiML, Shopify mandatory responses, OAuth callbacks), use the relay:
Requests to the public URL are proxied over a WebSocket to your machine and your local response (status, headers, body) goes back to the caller. It reconnects with backoff. The relay comes with the 7-day Pass or Pro.
| Anonymous | Free account | Pass (7 days, €5 once) / Pro (€9/month) | |
|---|---|---|---|
| Capture URLs | up to 30 new per day, each lasts 7 days | 1 permanent URL | 25 permanent URLs |
| History | 7 days | 7 days | 30 days |
CLI listen --forward, replay, sign, verify, MCP | ✓ | ✓ | ✓ |
| Relay (real tunnel to localhost) | ✓ | ||
| AI explanations and generated handlers | 3 free trials | 3 free trials | ✓ |
Details and the Business plan: webhook-toolkit.com/pricing. Everything that runs locally (signing, verifying, detection, forwarding) is free and stays free.
listen --forward works the same way and adds a stored inspector, provider/event detection, replay, signing and verification tools, a test-suite API and an MCP server.| Method | Returns |
|---|---|
createEndpoint({ name? }) | Endpoint: { token, url, inspectUrl, expiresAt, createdAt, response, … } |
listEndpoints() | Endpoint[] (API key required) |
getEndpoint(token) / deleteEndpoint(token) | Endpoint / void |
updateEndpoint(token, { name?, response?: { status?, body?, contentType? } }) | Endpoint |
listRequests(token, { limit?, after? }) | CapturedRequest[], newest first |
getRequest(token, id) / clearRequests(token) | CapturedRequest / void |
waitForRequest(token, { timeoutMs?, after?, filter?, signal? }) | CapturedRequest (rejects with code: "timeout") |
stream(token, onRequest, { signal?, after?, onOpen?, onReconnect? }) | Promise<void>: live SSE feed, reconnects and catches up on missed requests |
replayRequest(token, id, url) | server-side replay to a public URL |
explainRequest(token, id, { mode?, language? }) | AI explanation or handler (paid, 3 free trials) |
me(), listRelays(), createRelay() | account, plan, relays |
forwardRequest(request, target) re-sends a captured request from your machine (the same function behind listen --forward and replay). Errors are WebhookToolkitError with status (HTTP status, 0 for network errors), code (unauthorized, upgrade_required, plan_limit, expired, timeout, network_error, …) and upgradeUrl on 402 answers. Everything is typed; types ship with the package.
| Variable | Purpose |
|---|---|
WEBHOOK_TOOLKIT_KEY | API key (whk_…), created in your dashboard. Takes precedence over the saved key; --key overrides both. |
WEBHOOK_TOOLKIT_URL | API origin, e.g. http://localhost:3000 for a self-hosted instance. Same as --base-url. |
WEBHOOK_TOOLKIT_RELAY_TOKEN | Relay token for whtk relay. |
NO_COLOR / FORCE_COLOR | Terminal colors. |
whtk login stores the key in ~/.config/webhook-toolkit/config.json (or $XDG_CONFIG_HOME/webhook-toolkit/config.json) with mode 600. The same file remembers the last URL used by listen.
A capture URL's token is a capability: anyone holding it can read the requests sent to it. Use an account for anything sensitive; the owner's key is then required to change or delete the URL.
Node.js 18.17 or later. Runtime dependencies: @modelcontextprotocol/sdk and zod (MCP server) and ws (relay).
Issues and pull requests are welcome: see CONTRIBUTING.md. New providers for detection or signing are the easiest place to start.
MIT © 2026 Kipdev. Hosted service: webhook-toolkit.com.