webhooklocal

Documentation

Everything you need to receive webhooks on your laptop with webhooklocal. Start with the quick start; the rest is reference.

Overview

webhooklocal gives you a private HTTPS URL that never changes. Point a provider such as Stripe or GitHub at it, and every request they send is stored with its headers and body. The wl command-line tool forwards those requests to a server on your machine as they arrive, and you can replay any stored request later, with or without changes.

  • The URL is permanent. Paste it into the provider once. It stays the same across restarts, reboots, and new laptops, until you rotate it.
  • Nothing is dropped. Requests that arrive while your laptop is off are kept and marked not sent. Replay them when you are back.
  • Works behind NAT and firewalls. The CLI opens an outbound connection to webhooklocal. No ports to open, no tunnel to configure.

Quick start

  1. Sign in with your email address. A link that works once is sent to you; open it and press Sign in. Your first endpoint, my-endpoint, is created when you sign in.
  2. Copy your URL from the dashboard. It looks like https://webhooklocal.com/h/9f2c…b71e.
  3. Paste it into your provider's webhook settings (see Connect a provider).
  4. Install the CLI and sign in:
    curl -fsSL https://webhooklocal.com/install.sh | sh
    wl login
  5. Start your app, then forward requests to it:
    wl listen 3000

Each request now shows up in the dashboard and reaches http://localhost:3000 with the same method, path, headers, and body the provider sent.

Install the CLI

macOS and Linux

curl -fsSL https://webhooklocal.com/install.sh | sh

The script detects your OS and CPU, downloads the matching binary, checks its SHA-256 against checksums.txt, and installs webhooklocal plus the short alias wl into ~/.local/bin. Set WL_INSTALL_DIR to install somewhere else. It never uses sudo. You can read the script before running it.

If ~/.local/bin is not on your PATH, the script tells you. Add it in your shell profile:

export PATH="$HOME/.local/bin:$PATH"

Manual download

Download the binary for your platform, make it executable, and put it on your PATH. Every file is listed with its SHA-256 in checksums.txt, and VERSION names the current build.

PlatformFile
macOS, Apple siliconwl-darwin-arm64
macOS, Intelwl-darwin-amd64
Linux, x86-64wl-linux-amd64
Linux, ARM64wl-linux-arm64
Windows, x86-64wl-windows-amd64.exe
Windows, ARM64wl-windows-arm64.exe
curl -fsSLO https://webhooklocal.com/dl/wl-linux-amd64
chmod +x wl-linux-amd64
mv wl-linux-amd64 ~/.local/bin/wl

On macOS, a binary downloaded with a browser may be blocked by Gatekeeper on first run, because the builds are not notarized yet. Downloading with curl or the install script avoids that. Windows builds are provided but have had less testing than macOS and Linux.

Updating and uninstalling

Upgrade

wl upgrade

Downloads the current build for your platform, checks it against checksums.txt, and swaps it in place of the running binary; wl keeps pointing at it. Nothing is changed if the download or the checksum fails. wl upgrade --check only tells you whether a newer build exists, and wl listen prints a one-line notice when one does. If the install directory is not writable, run the install script again instead. wl version prints the build you have. To uninstall, delete webhooklocal and wl from the install directory and, optionally, ~/.config/webhooklocal/.

Sign in from the CLI

wl login

The CLI prints a short code and opens webhooklocal.com/cli/auth in your browser. Check that the code on the page matches the one in your terminal, then click Authorize. The code is valid for 10 minutes. On a machine without a browser, run wl login --no-browser and open the printed link anywhere you are signed in.

Signing in creates a token for this machine, saved in ~/.config/webhooklocal/config.json with permissions that only your user can read. Each token is listed under Settings → CLI tokens with the machine's name, where you can revoke it. wl logout revokes the token on the server and deletes the file.

To use a token without the login flow, for example in a script, pass --token or set WEBHOOKLOCAL_TOKEN.

Forward to localhost

wl listen 3000

This connects to webhooklocal and forwards every request that arrives at your endpoint to http://localhost:3000. Each line in the terminal is one request: the time, the method, the event name, your app's status code, and how long your app took.

● connected  https://webhooklocal.com/h/9f2c…b71e → http://localhost:3000
  Forwarding requests to my-endpoint. Ctrl+C to stop.
14:02:11  POST   invoice.paid                         200  12 ms
14:02:19  POST   charge.failed                        500  3 ms
14:03:40  POST   charge.failed                        200  4 ms replay
FlagWhat it does
--endpoint <name>Listen on a specific endpoint. Without it, your first endpoint is used.
--path /webhooks/stripePut this in front of every forwarded path, so a request to your URL reaches localhost:3000/webhooks/stripe. If the endpoint has a Forward path in its settings, that is used unless you pass --path.
--host <host>Forward to another host on your network instead of localhost.
--quietPrint only errors and failed requests.

The path after your URL is kept: a request to …/h/<token>/github is forwarded to localhost:3000/github, with its query string. All methods are forwarded. Headers are passed through as received, except hop-by-hop headers such as Connection and Transfer-Encoding.

If the connection drops, the CLI reconnects on its own, waiting one second at first and up to thirty seconds between attempts. Requests that arrive while no CLI is connected are stored and marked not sent. Your app's response is reported back and shown in the dashboard; a request that your app answered with 4xx or 5xx appears under the Failed filter.

If your app does not answer within 30 seconds, the request is marked as failed with a timeout. Replay it once your app is ready.

Connect a provider

Paste your endpoint URL wherever the provider asks for a webhook URL. You can add a path after the token to match the route your app expects. The dashboard names each request after the event when it can recognise it.

ProviderWhere to paste the URLEvent name shown
StripeDevelopers → Webhooks → Add endpoint. Choose the events to send.The type field, for example invoice.paid
GitHubRepository → Settings → Webhooks → Add webhook. Set the content type to application/json.The X-GitHub-Event header plus the action, for example pull_request.opened
ShopifySettings → Notifications → Webhooks, or the Admin API.The X-Shopify-Topic header, for example orders/create
TwilioPhone number → Messaging → A message comes in.The request path. Form-encoded bodies are shown as fields.
Anything elseAny HTTP client works. Try it: curl -X POST https://webhooklocal.com/h/<token>/test -d '{"hello":"world"}'The type field if the body is JSON, otherwise the path

Opening your URL in a browser shows a short page saying it is a webhook URL. That visit is still recorded as a GET request.

The dashboard

The dashboard at webhooklocal.com/app lists requests newest first and updates live as they arrive. The pill in the top bar shows whether a CLI is connected to the endpoint.

Finding a request

Search matches the event name, the path, the headers, and the body. The filter next to it narrows the list to Failed (not sent, or the latest outcome was a 4xx or 5xx) or Replayed. Older requests load in pages of 50.

Reading a request

Selecting a request shows what happened to it: when it was received, whether the CLI forwarded it, and your app's status and response time. Below that:

  • Body: JSON and XML are indented, form bodies are shown as fields with the raw body one click away, and anything that is not text is reported as binary.
  • Headers: every header as received. Authorization, Cookie, Proxy-Authorization, and X-Api-Key are masked until you click Reveal.
  • Query: the query string, decoded.
  • Replays: each replay of this request, with its status and timing.

Keyboard shortcuts

/Focus the search box
J / KSelect the next or previous request
RReplay to localhost
EOpen the editor to change and replay
CCopy as cURL
EscClose the editor

Send test in the top bar posts a small JSON request to your own URL, which is a quick way to check the whole path without involving a provider.

Notices

Wherever you are in the dashboard, a notice appears when a request arrives on an endpoint you are not looking at, and when a forward fails (your app answered 4xx or 5xx, or could not be reached). Each notice links to the request. Under Settings → Account → Notifications you can also allow desktop notifications; they repeat the same notices while the tab is in the background, and the choice is stored in that browser only.

Replay and edit

Replay to localhost sends the stored request to your app again, exactly as it was received, through your connected CLI. Use it to retry a request your app failed on, or to deliver requests that arrived while you were offline. The CLI prints replays with a replay tag, and the request's status in the list becomes the latest outcome.

Edit & replay opens the request in an editor where you can change the method, path, headers, and body before sending it through the CLI. This is useful for reproducing edge cases without waiting for the provider to send them.

  • Headers are one row each; remove a row or add one. Headers that Cloudflare or the proxy added on the way in (cf-*, x-forwarded-*, via) are listed apart and left out of the replay unless you tick Include them. Raw shows the same headers as name: value lines.
  • Body. JSON, XML and text bodies open in a code editor with syntax highlighting, line numbers, bracket matching, folding, search (Ctrl/⌘ F) and undo. JSON is pretty-printed when the editor opens, Format re-indents it after edits, and a linter underlines the first syntax error and names its line and column. Form bodies get one input per field, with Raw for the encoded text. Binary bodies are sent unchanged.
  • A body that is not valid JSON is not sent until you fix it or tick Send anyway.

On Free, edit & replay includes 10 edited replays a month, to localhost through the CLI. A replay counts when the method, path, headers or body were changed before sending, from the editor, wl replay or the MCP tool; a replay sent unchanged does not count and stays unlimited. A replay that could not be sent because no CLI was connected does not count either. The count starts again on the first day of each month (UTC), and the editor and Settings → Billing show how many are left. Solo and Pro have unlimited edited replays, replay to another URL and re-signing.

Replay to another URL (Solo and Pro) sends the stored or edited request to a URL you type, such as a staging server, instead of through the CLI. In the editor, switch Send to from localhost via CLI to A URL. The request's path is added after the URL's path, like the CLI's forward path: with https://staging.example.com/hooks and a request to /stripe, the replay goes to https://staging.example.com/hooks/stripe. The target's status and the first 64 KB of its body are shown and recorded under Replays. Only http and https on port 80, 443 or an unprivileged port can be used; private, loopback and other internal addresses are refused after the host name is resolved; redirects are not followed; and the target has 30 seconds to answer.

Changing the body breaks the provider's signature, because the signature was computed over the original bytes, and Stripe rejects signatures older than five minutes by default even when nothing changed. With the endpoint's signing secret saved (see Signature checks), the editor re-signs the edited body with a fresh timestamp, so your handler's verification passes. Without it, either skip verification in your handler while testing, or verify only when the request is not a replay.

Copy as cURL copies a curl command with the request's method, path, query, headers and body. It sends to your webhooklocal URL, so running it stores a new request that is forwarded to localhost when wl listen is running; to call your app directly, replace the URL in the command. Masked headers such as Authorization are left out unless you reveal them on the Headers tab and copy from there, and headers added by Cloudflare or the proxy are always left out. Text bodies are copied as received; binary bodies are not reproduced exactly, so replay those instead.

Signature checks

Stripe and GitHub sign every webhook with a secret you can read in their dashboards. Save that secret in the endpoint's settings and webhooklocal tells you, on each request, whether the signature is right for the body that arrived.

  1. Find the secret: Stripe shows it as Signing secret (whsec_…) on the webhook endpoint's page; GitHub uses the Secret you typed when creating the webhook.
  2. Open Endpoints → settings → Signing secret, paste it, and save. It is stored encrypted and never shown again.
  3. Each request that carries a Stripe-Signature or X-Hub-Signature-256 header now shows a label next to its name: signature valid, signature invalid (wrong secret, or the body was changed in transit), or not checked while no secret is saved. For Stripe, the label also says how old the timestamp was when the request arrived, and warns when it is past Stripe's five-minute tolerance.
  4. In Edit & replay, Re-sign with the saved secret is ticked by default for signed requests. The edited body gets a new signature (and, for Stripe, a current timestamp) before it is sent, through the CLI or to a URL. Untick it to send the original header unchanged.

Checks happen when you look at a request, not when it arrives, so saving a secret later also labels requests that are already stored. Requests from other providers show no label. Signatures are checked against the body exactly as received; if your framework re-serialises JSON before verifying, that is a bug in the handler, not in the signature.

What the provider receives

Providers retry when a webhook fails, and some disable the endpoint after repeated failures. What your URL answers is therefore a setting per endpoint:

  • Pass through your app's response (the default). While a CLI is connected, the provider gets the status code and body your app returned, so its retries behave as they would in production. If no CLI is connected, or your app has not answered within 8 seconds, the provider gets 200 and the request is stored for later.
  • Always 200 OK, right away. The provider never retries, even when your app fails.

Only the status and body are passed through, never your app's response headers. The body is sent with a safe content type, so a webhook URL can never serve a page that runs in a browser.

Endpoint settings

Open the sliders icon next to an endpoint, or Endpoints in the sidebar.

SettingWhat it does
NameShown in the dashboard and used by wl listen --endpoint. Lowercase letters, numbers, and dashes, up to 40 characters.
Forward pathPut in front of every path when the CLI forwards a request, for example /webhooks/stripe. wl listen --path overrides it.
Reply to the providerPass-through or always 200. See above.
Accept requestsTurn off to answer new requests with 503 while you work on something else. Stored requests stay.
Signing secretThe provider's webhook secret, for signature checks and re-signed replays. Stored encrypted. Remove it to stop checking.
Delete all requestsRemoves every stored request for this endpoint. The URL keeps working.
Rotate URLIssues a new URL and retires the old one at once; the old one answers 404. Use it if the URL leaked. You will need to update the provider.
Delete endpointRemoves the endpoint and all its requests.

The number of endpoints depends on your plan: 1 on Free, 5 on Solo, 25 on Pro. If you move to a plan with fewer endpoints, your oldest endpoints keep working and the rest are paused: their URLs answer 410 and store nothing, and wl listen refuses them. Stored requests are kept and can still be viewed and replayed. Upgrading or deleting endpoints resumes them.

Limits and retention

LimitValue
Request body1 MiB. Larger requests are answered with 413 and not stored.
Rate per URLAbout 50 requests per second, with bursts of 100. Above that the provider gets 429.
Rate per sender1,000 requests per minute from one IP address, then 429.
Time waiting for your app30 seconds, then the request is marked as failed.
History on Free24 hours, and the newest 100 requests per endpoint. Older requests are deleted, oldest first.
History on Solo and Pro30 and 90 days.
Monthly requests100 on Free, 50,000 on Solo, 250,000 on Pro. Going over never drops a request: everything is still stored and forwarded, and the dashboard asks you to upgrade.
Edited replays10 a month on Free, to localhost (see Replay and edit). Unlimited on Solo and Pro. Unchanged replays are unlimited on every plan.

Retention runs every ten minutes. A request that has been deleted cannot be replayed.

Security

  • Your URL is a secret. The token in it is 128 bits of randomness, and anyone who has the URL can send requests to it. Treat it like a password: do not commit it, and rotate it if it leaks.
  • What is stored. The full request: method, path, query, headers, and body, for as long as your plan's history allows. Masked headers are hidden in the dashboard but stored. Do not point production systems at webhooklocal; it is for development.
  • Your sessions. Browser sessions last 30 days. Sign-in links work once and expire after 15 minutes. CLI tokens last until you revoke them, and wl logout revokes the one on that machine.
  • Transport. Everything is served over HTTPS. The CLI connects outbound only.
  • Reporting a problem. Email [email protected]. Suspected abuse of a webhooklocal URL: [email protected].

CLI reference

The binary is webhooklocal; wl is an alias installed next to it.

CommandWhat it does
wl login [--no-browser]Sign in on this machine with a code you confirm in the browser.
wl logoutRevoke this machine's token and delete the saved config.
wl listen <port> [--endpoint name] [--path /p] [--host h] [--quiet]Forward requests to localhost:<port>. See Forward to localhost.
wl endpoints [--json]List your endpoints, their URLs, and whether a CLI is connected to each.
wl requests [--endpoint name] [--limit n] [--before id] [--q text] [--failed] [--replayed] [--json]List stored requests, newest first, with each one's latest outcome.
wl request <id> [--reveal] [--body] [--json]Show one request: headers (masked ones hidden unless --reveal), body, signature check, replays. --body prints only the body.
wl replay <id> [--to url] [--method M] [--path /p] [--body file|-] [-H 'Name: value'] [--no-resign] [--json]Replay a request to localhost through the CLI, or to a URL. Any flag edits the copy that is sent; an edited body is re-signed with the saved secret unless --no-resign.
wl whoamiShow the signed-in account, its plan, and the server.
wl mcpRun the MCP server over stdio for AI coding tools. wl mcp config prints the registration snippet. See MCP server.
wl upgrade [--check]Replace this binary with the current build, after verifying its checksum. With --check, only report whether one exists.
wl versionPrint the build you have installed.
Global flag or variableWhat it does
--token, WEBHOOKLOCAL_TOKENUse this token instead of the saved login.
--server, WEBHOOKLOCAL_SERVERTalk to another server. The default is https://webhooklocal.com.

Settings are read in this order: flags, then environment variables, then ~/.config/webhooklocal/config.json. The CLI exits with status 2 when it is not signed in or the token was revoked, and 1 for any other error.

With an AI coding tool

Claude Code, Cursor and similar tools can use webhooklocal today through the CLI and the dashboard; nothing extra to install. What works now:

  • Let the agent watch requests arrive. Run wl listen 3000 in a terminal the agent can read (its own background shell, or a tmux pane). Every forwarded request is printed with its method, path, event name, your app's status and the time it took, so the agent sees the real traffic while it edits the handler.
  • Give it the exact request. Copy as cURL on any request produces a command with its method, path, headers and text body as received (masked headers only if you revealed them; binary bodies are not exact). It sends to your webhooklocal URL; replace that with your local address to call your app directly. Paste it into the chat, or save it as a file in the project and tell the agent to run it after each change.
  • Replay instead of re-triggering. After the agent changes the handler, replay the stored request from the dashboard (or press R) rather than asking the provider to send a new event. Edited replays break the provider's signature, so the handler should skip verification for replays while testing.
  • Machine-readable everything. wl endpoints --json, wl requests --json, wl request <id> --json and wl replay <id> --json print the same data the dashboard shows, as JSON. The CLI reads WEBHOOKLOCAL_TOKEN and WEBHOOKLOCAL_SERVER, so it can run from a script. The HTTP API behind them is GET /api/requests, GET /api/requests/{id} and POST /api/requests/{id}/replay with a bearer token from ~/.config/webhooklocal/config.json.
  • Docs for the agent. /llms.txt is a plain-text summary of this page for tools that read documentation.

Before you let an agent read stored requests, remember that webhook payloads contain your customers' data and your providers' secrets, and whatever the agent reads goes to the model provider you use. Masked headers such as Authorization are left out of cURL output unless you reveal them.

MCP server

wl mcp runs a Model Context Protocol server over stdio with four tools: list_endpoints, list_requests, get_request and replay_request. They call the same API as the commands above with the token from wl login, so the agent sees exactly what you see, under your plan's limits, and nothing is stored on the machine. Masked headers stay masked unless the agent asks for reveal. Register it once:

# Claude Code
claude mcp add webhooklocal -- wl mcp

# Cursor, Windsurf and others: add to the tool's MCP settings
{"mcpServers": {"webhooklocal": {"command": "wl", "args": ["mcp"]}}}

wl mcp config prints the same with the full path to the binary, for tools that do not search PATH. Then ask the agent things like "show the last failed Stripe request and replay it after you fix the handler". Nothing in this is specific to one tool; any MCP client works.

Not available yet

These are planned and not built. They are listed so the pricing page is not misleading.

  • Signature checks for providers other than Stripe and GitHub.
  • Team members, Slack and email alerts, and custom subdomains.

Help

Email [email protected]. Include the endpoint name and, for a specific request, its number (shown as #123 in the detail view). Never include your endpoint URL in a public place.