Live tunnels
whk tunnel --live relays each webhook to your local server while the sender waits, so the sender gets your app's real answer. The request is captured either way, with your app's response stored next to it.
Updated Nov 2026
A plain whk tunnel captures each webhook, answers the sender at once with the endpoint's mock response (or 200), and then replays the request to your local server. That suits most webhooks, but not the ones where the response matters: a Slack slash command shows your answer in the channel, Twilio reads TwiML from it, and some providers check a handshake answer before they turn a webhook on. With --live, the sender waits while your local app answers, and gets that answer:
whk tunnel 3000 --liveThe tunnel creates an endpoint (or uses --endpoint <slug>), prints its URL, and says Live relay connected once the sender's requests can reach your app. Each relayed request is listed with your app's status and how long it took, and when the sender got a 503 in your app's place, why: the app did not answer in time, nothing answered on the port, the tunnel was busy, or the app's answer was not passed back.
Every request is still captured first, so the dashboard, CLI, SDKs and MCP server show it as usual, now with your app's response next to it.
What changes with --live
whk tunnel | whk tunnel --live | |
|---|---|---|
| The sender gets | The endpoint's mock response, or 200, at once | Your local app's response |
| Your app gets the request | Replayed after the capture | While the sender waits |
| Request to your app | Sensitive headers filtered, -H added | The sender's request: method, path, headers and exact body, with -H added, plus X-Forwarded-Host, X-Forwarded-Proto, X-Forwarded-Prefix and X-Forwarded-Uri |
| Mock responses and rules | Answer the sender | Not used: your app answers |
| Stored with the request | The answer the sender got | What the sender got from your app: status, headers as passed on, and the first 64 KB of the body |
| Emails | Posted to your server | Posted to your server, the same way |
Because the request reaches your app as the sender sent it, your handler can check the provider's signature with your real signing secret, as it would in production.
Signatures over the URL. Some providers sign the public URL they called, not just the body: Twilio, for one. Your app receives the request at localhost, without the /w/<slug> prefix, so it cannot see that URL directly. Rebuild it from the forwarded headers: X-Forwarded-Proto (https), X-Forwarded-Host (go.webhooks.cc) and X-Forwarded-Prefix (/w/<slug>), followed by X-Forwarded-Uri, the path and query as the sender sent them after the prefix. Use X-Forwarded-Uri rather than the path your app received: with a target that has a path (whk tunnel 8080/api --live), your app gets /api/..., which is not what the sender signed. For Twilio, validate against https://go.webhooks.cc/w/<slug> plus X-Forwarded-Uri, the URL you gave Twilio. Many frameworks read the host and protocol headers when you tell them to trust the proxy in front of them.
Emails have no sender waiting for an answer, so they keep arriving through the stream exactly as with a plain tunnel (emails), with the same --email-format, --email-path and --no-email flags.
When your app does not answer
The request is captured whatever happens. What the sender gets:
| Situation | The sender gets |
|---|---|
whk stopped or lost its connection less than 2 minutes ago | 503 |
whk stopped more than 2 minutes ago, or never started | The endpoint's mock response, or 200 |
| Nothing listens on the local port | 503 |
| Your app sends no response within 25 seconds | 503 |
| Your app answers, with any status | That answer |
Every 503 that stands in for your app carries the reason as JSON, so the sender's logs say what went wrong:
{ "error": "Nothing is running on port 3000 on the computer running whk." }It is a 503 rather than a 502 or 504 because webhooks.cc sits behind Cloudflare, which replaces a 502 or 504 from the server behind it with its own page (error code: 502), and the reason would be lost. The request's stored outcome tells the cases apart: offline, unreachable, timeout, busy (the tunnel had too many requests in flight) or refused, and whk names the reason on the request's line as it happens (a capture made while whk was offline reaches it later, from the stream).
Senders that retry on 5xx will try again later, the way they would if your real server were down, and you see each failure in the request list. The 2-minute grace covers reconnects: a sender that hits the gap gets an error and retries, instead of a success your app never saw. Once the grace is over, the endpoint answers as a plain endpoint again.
A connection that goes silent without closing (a laptop that sleeps, a network that changes) is noticed within about a minute, and whk reconnects. While the relay is not connected and whk is still running, it forwards each capture from the stream to your app like a plain tunnel, and says so once: your app still gets every request, after the sender has had its 503 or the mock response. Captures the relay already carried are not sent twice.
When the computer was offline for a while (asleep, or off the network), the relay often reconnects before the stream has caught up. The stream then brings the captures made meanwhile, which the relay never carried. whk gives the relay up to 40 seconds to claim each one, skips any that webhooks.cc shows the relay dealt with after all (your app answered, or the sender got a 503 for a slow answer or a busy tunnel and retries), and then forwards the rest to your app, once each, and says how many. Captures made while whk was not running at all are not forwarded.
What reaches the sender
A live tunnel answers webhook senders, not browsers, so the answer is kept to what an API returns:
- Up to 1 MB. An answer that says it is larger gets the sender a
503instead. One that streams past 1 MB without saying so is cut off there: the sender has already had the status and headers, so it gets a broken stream, and the request is stored with your app's status (often200) and the outcomerefused. Treatrefusedas the sender having seen a failure. - API-shaped types only: JSON, XML, text (HTML included, under the sandbox below) and form data. Script, including text types browsers run as script (
text/javascript,text/jscript,text/livescriptand the like), images, video, files and anything sent as a download (Content-Disposition: attachment) get the sender a503, andwhksays why. - Answers without a type of up to 64 KB are passed on as
text/plain(an emptyres.end()included). A larger one without a type gets the sender a503. - No cookies or browser security headers.
Set-Cookie,Strict-Transport-Security,Content-Security-PolicyandX-Frame-Optionsfrom your app are not passed on; the sender's copy carriesX-Content-Type-Options: nosniffandContent-Security-Policy: sandboxinstead.
The stored response is what the sender got, not your app's raw answer: the headers above are already removed or added, and only the first 64 KB of the body is kept. A sender that hangs up before your app has finished does not cut the record short: the rest of the answer is still read for the request, up to those 64 KB and for 10 seconds at most.
Limits
- Live requests count against your request quota like any capture. They do not count against the shared data of
whk share. - An account can have up to 5 live tunnels open at once, one per endpoint.
- An account's live requests waiting for an answer at the same time are capped, so one slow local app cannot hold up the rest of the account's captures, and live requests have room of their own that visitors to the account's previews cannot use up. Past the cap, the sender gets
503withRetry-After. - A request whose headers come to more than 64 KB gets the sender a
431fromwhkwithout reaching your app. - Your local app has 25 seconds to start answering. Slack, for one, gives a slash command 3 seconds, so answer fast and do slow work afterwards, as you would in production.
Targets, paths and headers
The target is a port on this machine, written as for a plain tunnel: 3000, 3000/api, localhost:3000, 127.0.0.1:3000 or http://localhost:3000/api. localhost tries IPv4, then IPv6; 127.0.0.1 and [::1] connect to exactly that address. Your app must speak plain HTTP: a local HTTPS server is refused when the tunnel starts, since the relay copies bytes to the port and cannot speak TLS to it.
The path after the endpoint's URL goes to your app: a request to https://go.webhooks.cc/w/acme-7f2a/slack/commands arrives at localhost:3000/slack/commands. A target with a path puts requests under it (whk tunnel 8080/api --live sends /slack/commands to /api/slack/commands), and -H headers replace any of the same name on the way.
JSON events
With --json, the tunnel prints live_connected when the live session opens, relayed for each request (method, path, status, duration_ms, request_id, the capture's id, as in the dashboard and the API, and outcome: answered for your app's own answer, or timeout, unreachable, busy or refused when the sender got a 503 in its place; from whk 1.20.3), live_reconnected and live_retrying around network trouble, live_fallback once when it starts forwarding captures from the stream while the relay is down (those arrive as forwarded events, as do captures from while the computer was offline; a capture the relay already carried, matched by its id, is never sent twice), notice, and live_stopped when it ends, Ctrl-C and SIGTERM included ("you stopped it on this computer", status 0). Emails keep the plain tunnel's forwarded events.
When the live session is refused before it ever opens (the account's live tunnels are all in use, or the endpoint is not yours), whk prints why and exits with the status its reason has in the exit status table: 5 when the plan has no live tunnel left, 4 when the endpoint is not yours, 2 for a tunnel address it cannot use. Starting a second whk tunnel --live on the same endpoint takes the relay over: the first one is told it was replaced and ends. A session that was live and is then ended (stopped on webhooks.cc, replaced, the endpoint unshared) ends with live_stopped and status 0. Refusals that do not come from webhooks.cc itself (a proxy or firewall page, a rate limit) are retried, not taken as the end.