@cmer/localhook 1.1.0 → 1.2.0

package/README.md

@@ -34,6 +34,12 @@ npx @cmer/localhook --port 8080 --tailscale
 
 # Allow dashboard access from the public URL (password-protected)
 npx @cmer/localhook --tailscale --allow-remote-access --password mysecret
+
+# Forward webhooks to your local app
+npx @cmer/localhook --forward-to http://localhost:4444
+
+# Forward with a base path
+npx @cmer/localhook --forward-to http://localhost:4444/api/webhooks
 ```
 
 | Flag | Short | Description |
@@ -44,6 +50,7 @@ npx @cmer/localhook --tailscale --allow-remote-access --password mysecret
 | `--allow-remote-access` | | Allow dashboard/API access from non-localhost (e.g. via tunnel) |
 | `--password <value>` | | Require HTTP Basic Auth for remote dashboard/API access (localhost is never challenged) |
 | `--data-file <path>` | | Path to data file (default: `~/.localhook/data.json`) |
+| `--forward-to <url>` | | Forward incoming webhooks to a local app (preserves method, path, headers, body) |
 | `--help` | `-h` | Show help |
 
 Open `http://localhost:3000` in your browser to see the dashboard.
@@ -74,6 +81,31 @@ Incoming requests are also logged in the terminal:
 - **Zero config** -- no database, no build step, no accounts
 - **Terminal logging** -- see requests in your terminal without opening the dashboard
 
+## Webhook Forwarding
+
+Use `--forward-to` to forward incoming webhooks to your local application while still capturing them in the dashboard:
+
+```bash
+npx @cmer/localhook --forward-to http://localhost:4444
+```
+
+Every captured webhook is forwarded synchronously — your app receives the original HTTP method, path, query string, headers (including signature headers like `x-stripe-signature`), and body. The caller (e.g. Stripe) receives your app's actual response, so retries work correctly on 5xx errors.
+
+You can also specify a base path that gets prepended to the webhook path:
+
+```bash
+# Webhook to /events → forwarded to http://localhost:4444/api/webhooks/events
+npx @cmer/localhook --forward-to http://localhost:4444/api/webhooks
+```
+
+The dashboard shows forwarding results: status code, duration, and response body for each request. If the target is unreachable, the caller receives a 502 and the error is displayed in the dashboard.
+
+Combine with a tunnel for end-to-end webhook testing:
+
+```bash
+npx @cmer/localhook --cloudflare --forward-to http://localhost:4444
+```
+
 ## Testing with External Services
 
 If you need to receive webhooks from external services like Stripe, GitHub, or Shopify, they need a public URL to send requests to.

package/cli.js

@@ -10,6 +10,7 @@ let allowRemoteAccess = false;
 let password = null;
 let poll = false;
 let dataFile = null;
+let forwardTo = null;
 
 for (let i = 0; i < args.length; i++) {
   if ((args[i] === '--port' || args[i] === '-p') && args[i + 1]) {
@@ -29,6 +30,9 @@ for (let i = 0; i < args.length; i++) {
   } else if (args[i] === '--data-file' && args[i + 1]) {
     dataFile = args[i + 1];
     i++;
+  } else if (args[i] === '--forward-to' && args[i + 1]) {
+    forwardTo = args[i + 1];
+    i++;
   } else if (args[i] === '--help' || args[i] === '-h') {
     console.log(`
   localhook - Local webhook testing tool
@@ -44,6 +48,7 @@ for (let i = 0; i < args.length; i++) {
     --password <value>            Require HTTP Basic Auth for remote dashboard/API access
     --poll                        Force polling instead of SSE for dashboard updates
     --data-file <path>            Path to data file (default: ~/.localhook/data.json)
+    --forward-to <url>            Forward incoming webhooks to a local app (e.g. http://localhost:4444)
     -h, --help                    Show this help message
 `);
     process.exit(0);
@@ -55,4 +60,15 @@ if (tailscale && cloudflare) {
   process.exit(1);
 }
 
-createServer(port, { tailscale, cloudflare, allowRemoteAccess, password, poll, dataFile });
+if (forwardTo) {
+  try {
+    const u = new URL(forwardTo);
+    if (u.protocol !== 'http:' && u.protocol !== 'https:') throw new Error();
+    forwardTo = forwardTo.replace(/\/+$/, '');
+  } catch {
+    console.error('\n  Error: --forward-to must be a valid http:// or https:// URL.\n');
+    process.exit(1);
+  }
+}
+
+createServer(port, { tailscale, cloudflare, allowRemoteAccess, password, poll, dataFile, forwardTo });

package/lib/server.js

@@ -186,6 +186,54 @@ function generateId() {
   return crypto.randomBytes(8).toString('hex');
 }
 
+const FORWARD_TIMEOUT_MS = 10000;
+const MAX_RESPONSE_BODY = 100 * 1024;
+
+async function forwardWebhook(webhook, forwardTo) {
+  const targetUrl = forwardTo + webhook.path;
+  const headers = {};
+  for (const [k, v] of Object.entries(webhook.headers)) {
+    const lower = k.toLowerCase();
+    if (lower === 'host' || lower === 'connection' || lower === 'content-length' || lower === 'transfer-encoding') continue;
+    headers[k] = v;
+  }
+  try {
+    const targetHost = new URL(targetUrl).host;
+    headers['host'] = targetHost;
+  } catch {}
+
+  const fetchOptions = {
+    method: webhook.method,
+    headers,
+    signal: AbortSignal.timeout(FORWARD_TIMEOUT_MS),
+  };
+  if (webhook.method !== 'GET' && webhook.method !== 'HEAD' && webhook.body) {
+    fetchOptions.body = webhook.body;
+  }
+
+  const start = Date.now();
+  try {
+    const res = await fetch(targetUrl, fetchOptions);
+    let responseBody = await res.text();
+    if (responseBody.length > MAX_RESPONSE_BODY) {
+      responseBody = responseBody.slice(0, MAX_RESPONSE_BODY) + '\n... (truncated)';
+    }
+    return {
+      url: targetUrl,
+      status: res.status,
+      statusText: res.statusText,
+      responseBody,
+      duration: Date.now() - start,
+    };
+  } catch (err) {
+    return {
+      url: targetUrl,
+      error: err.name === 'TimeoutError' ? 'Request timed out (10s)' : err.message,
+      duration: Date.now() - start,
+    };
+  }
+}
+
 function createServer(port, options = {}) {
   if (options.dataFile) {
     dataFile = path.resolve(options.dataFile);
@@ -274,7 +322,7 @@ function createServer(port, options = {}) {
   });
 
   app.get('/_/api/public_url', (req, res) => {
-    res.json({ url: publicUrl, service: tunnelService, poll: !!options.poll });
+    res.json({ url: publicUrl, service: tunnelService, poll: !!options.poll, forwardTo: options.forwardTo || null });
   });
 
   app.get('/_/api/webhooks', (req, res) => {
@@ -312,7 +360,7 @@ function createServer(port, options = {}) {
 
     const chunks = [];
     req.on('data', chunk => chunks.push(chunk));
-    req.on('end', () => {
+    req.on('end', async () => {
       const body = Buffer.concat(chunks).toString('utf-8');
 
       const webhook = {
@@ -327,12 +375,25 @@ function createServer(port, options = {}) {
         timestamp: new Date().toISOString(),
       };
 
+      if (options.forwardTo) {
+        webhook.forward = await forwardWebhook(webhook, options.forwardTo);
+      }
+
       // Log to terminal
       const d = new Date(webhook.timestamp);
       const time = d.toLocaleDateString() + ' ' + d.toLocaleTimeString();
       const ct = webhook.headers['content-type'] || '';
       const sizeStr = webhook.size > 0 ? ` ${webhook.size}b` : '';
-      console.log(`  \x1b[2m${time}\x1b[0m  \x1b[1m${webhook.method.padEnd(7)}\x1b[0m ${webhook.path}\x1b[2m${sizeStr}${ct ? '  ' + ct : ''}\x1b[0m`);
+      let forwardInfo = '';
+      if (webhook.forward) {
+        if (webhook.forward.error) {
+          forwardInfo = `  \x1b[31m=> ERR ${webhook.forward.error}\x1b[0m`;
+        } else {
+          const statusColor = webhook.forward.status < 400 ? '\x1b[32m' : webhook.forward.status < 500 ? '\x1b[33m' : '\x1b[31m';
+          forwardInfo = `  ${statusColor}=> ${webhook.forward.status} ${webhook.forward.duration}ms\x1b[0m`;
+        }
+      }
+      console.log(`  \x1b[2m${time}\x1b[0m  \x1b[1m${webhook.method.padEnd(7)}\x1b[0m ${webhook.path}\x1b[2m${sizeStr}${ct ? '  ' + ct : ''}\x1b[0m${forwardInfo}`);
 
       webhooks.unshift(webhook);
       if (webhooks.length > MAX_WEBHOOKS) {
@@ -341,7 +402,15 @@ function createServer(port, options = {}) {
       saveData();
       broadcast({ type: 'webhook', webhook });
 
-      res.status(200).json({ ok: true, id: webhook.id });
+      if (webhook.forward) {
+        if (webhook.forward.error) {
+          res.status(502).json({ ok: false, error: webhook.forward.error, id: webhook.id });
+        } else {
+          res.status(webhook.forward.status).send(webhook.forward.responseBody);
+        }
+      } else {
+        res.status(200).json({ ok: true, id: webhook.id });
+      }
     });
   });
 
@@ -355,6 +424,7 @@ function createServer(port, options = {}) {
     const magenta = '\x1b[35m';
 
     const passwordLine = options.password ? `\n  ${magenta}Password${reset}      enabled (remote only)` : '';
+    const forwardLine = options.forwardTo ? `\n  ${yellow}Forwarding${reset}    ${options.forwardTo}` : '';
 
     if (options.tailscale || options.cloudflare) {
       const serviceName = options.tailscale ? 'Tailscale Funnel' : 'Cloudflare Quick Tunnel';
@@ -372,7 +442,7 @@ function createServer(port, options = {}) {
   ${green}Webhook URL${reset}   http://localhost:${port}${dim}/any-path${reset}
                 ${result.url}${dim}/any-path${reset}
 
-  ${cyan}Dashboard${reset}     http://localhost:${port}/${options.allowRemoteAccess ? `\n                ${result.url}/` : ''}${passwordLine}
+  ${cyan}Dashboard${reset}     http://localhost:${port}/${options.allowRemoteAccess ? `\n                ${result.url}/` : ''}${passwordLine}${forwardLine}
 
   ${dim}Send any HTTP request to capture it.${reset}
   ${dim}Press Ctrl+C to stop.${reset}
@@ -404,7 +474,7 @@ function createServer(port, options = {}) {
   ${bold}LocalHook${reset} is running!
 
   ${green}Webhook URL${reset}   http://localhost:${port}${dim}/any-path${reset}
-  ${cyan}Dashboard${reset}     http://localhost:${port}/${passwordLine}
+  ${cyan}Dashboard${reset}     http://localhost:${port}/${passwordLine}${forwardLine}
 
   ${dim}Send any HTTP request to capture it.${reset}
   ${dim}Press Ctrl+C to stop.${reset}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cmer/localhook",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Webhook interceptor and testing tool. Capture and inspect HTTP requests locally with a real-time dashboard. Test Stripe, GitHub, Shopify, Twilio, SendGrid, and any other webhooks without third-party services. Zero config",
   "author": "Carl Mercier",
   "license": "MIT",
@@ -31,7 +31,7 @@
     "server"
   ],
   "engines": {
-    "node": ">=14"
+    "node": ">=18"
   },
   "scripts": {
     "test": "node --test test/*.test.js"

package/public/index.html

@@ -563,6 +563,35 @@ body {
 [data-theme="light"] .webhook-item .delete-btn:hover {
   background: rgba(220,38,38,0.08);
 }
+
+/* Forward badges */
+.forward-badge {
+  display: inline-flex;
+  align-items: center;
+  padding: 1px 6px;
+  border-radius: 3px;
+  font-size: 9px;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  flex-shrink: 0;
+}
+
+.forward-badge.success { background: rgba(74,222,128,0.12); color: var(--green); }
+.forward-badge.client-error { background: rgba(251,146,60,0.12); color: var(--orange); }
+.forward-badge.server-error { background: rgba(248,113,113,0.12); color: var(--red); }
+.forward-badge.error { background: rgba(248,113,113,0.12); color: var(--red); }
+
+[data-theme="light"] .forward-badge.success { background: rgba(22,163,74,0.1); }
+[data-theme="light"] .forward-badge.client-error { background: rgba(234,88,12,0.1); }
+[data-theme="light"] .forward-badge.server-error { background: rgba(220,38,38,0.1); }
+[data-theme="light"] .forward-badge.error { background: rgba(220,38,38,0.1); }
+
+.forward-info {
+  margin-top: 4px;
+  font-size: 10px;
+  color: var(--text-muted);
+  font-family: var(--mono);
+}
 </style>
 </head>
 <body>
@@ -810,6 +839,16 @@ function copyBody() {
   navigator.clipboard.writeText(text).then(() => showToast('Copied!'));
 }
 
+function copyForwardBody() {
+  const w = state.webhooks.find(w => w.id === state.selected);
+  if (!w || !w.forward || !w.forward.responseBody) return;
+  let text = w.forward.responseBody;
+  if (state.formatJson) {
+    try { text = JSON.stringify(JSON.parse(w.forward.responseBody), null, 2); } catch {}
+  }
+  navigator.clipboard.writeText(text).then(() => showToast('Copied!'));
+}
+
 function toggleFormat() {
   state.formatJson = !state.formatJson;
   renderDetail();
@@ -827,17 +866,31 @@ function renderList() {
   const n = state.webhooks.length;
   count.textContent = `${n} request${n !== 1 ? 's' : ''}`;
 
-  list.innerHTML = state.webhooks.map(w => `
+  list.innerHTML = state.webhooks.map(w => {
+    let forwardBadge = '';
+    if (w.forward) {
+      if (w.forward.error) {
+        forwardBadge = '<span class="forward-badge error">ERR</span>';
+      } else if (w.forward.status >= 500) {
+        forwardBadge = `<span class="forward-badge server-error">${w.forward.status}</span>`;
+      } else if (w.forward.status >= 400) {
+        forwardBadge = `<span class="forward-badge client-error">${w.forward.status}</span>`;
+      } else {
+        forwardBadge = `<span class="forward-badge success">${w.forward.status}</span>`;
+      }
+    }
+    return `
     <div class="webhook-item ${w.id === state.selected ? 'selected' : ''}"
          onclick="selectWebhook('${w.id}')">
       <span class="method-badge method-${w.method}">${esc(w.method)}</span>
       <div class="webhook-item-info">
         <div class="webhook-item-path">${esc(w.path)}</div>
-        <div class="webhook-item-time">${formatTime(w.timestamp)}</div>
+        <div class="webhook-item-time">${formatTime(w.timestamp)}${forwardBadge ? ' ' + forwardBadge : ''}</div>
       </div>
       <button class="delete-btn" onclick="deleteWebhook('${w.id}', event)" title="Delete">&times;</button>
     </div>
-  `).join('');
+  `;
+  }).join('');
 }
 
 function renderDetail() {
@@ -941,6 +994,55 @@ function renderDetail() {
         </div>
         ${bodyHtml}
       </div>
+
+      ${w.forward ? (() => {
+        let fwdBodyHtml = '';
+        if (w.forward.responseBody) {
+          let fwdContent = w.forward.responseBody;
+          let fwdHighlighted = false;
+          if (state.formatJson) {
+            try {
+              const parsed = JSON.parse(w.forward.responseBody);
+              fwdContent = JSON.stringify(parsed, null, 2);
+              fwdHighlighted = true;
+            } catch {}
+          }
+          const fwdDisplay = fwdHighlighted ? highlightJson(fwdContent) : esc(fwdContent);
+          fwdBodyHtml = '<pre class="body-pre ' + (state.wordWrap ? 'word-wrap' : '') + '">' + fwdDisplay + '</pre>';
+        } else {
+          fwdBodyHtml = '<p class="none-text">No response body</p>';
+        }
+        return `
+        <div class="section">
+          <div class="section-header">Forwarding</div>
+          <div class="detail-grid" style="max-width:600px">
+            <div class="label">Target URL</div>
+            <div class="value" style="font-family:var(--mono);font-size:11px">${esc(w.forward.url)}</div>
+            <div class="label">Status</div>
+            <div class="value">${w.forward.error
+              ? '<span class="forward-badge error">ERR</span> ' + esc(w.forward.error)
+              : w.forward.status >= 500
+                ? '<span class="forward-badge server-error">' + w.forward.status + '</span> ' + esc(w.forward.statusText)
+                : w.forward.status >= 400
+                  ? '<span class="forward-badge client-error">' + w.forward.status + '</span> ' + esc(w.forward.statusText)
+                  : '<span class="forward-badge success">' + w.forward.status + '</span> ' + esc(w.forward.statusText)
+            }</div>
+            <div class="label">Duration</div>
+            <div class="value">${w.forward.duration}ms</div>
+          </div>
+        </div>
+        <div class="section">
+          <div class="section-header">
+            Response Body
+            <div class="body-controls">
+              <label><input type="checkbox" ${state.formatJson ? 'checked' : ''} onchange="toggleFormat()"> Format JSON</label>
+              <label><input type="checkbox" ${state.wordWrap ? 'checked' : ''} onchange="toggleWrap()"> Word Wrap</label>
+              <button class="btn" onclick="copyForwardBody()">Copy</button>
+            </div>
+          </div>
+          ${fwdBodyHtml}
+        </div>`;
+      })() : ''}
     </div>`;
 }
 
@@ -1032,6 +1134,12 @@ loadWebhooks();
     const res = await fetch('/_/api/public_url');
     const info = await res.json();
     if (info.poll) forcePoll = true;
+    if (info.forwardTo) {
+      const fwdEl = document.createElement('div');
+      fwdEl.className = 'forward-info';
+      fwdEl.textContent = 'Forwarding to ' + info.forwardTo;
+      document.getElementById('url-box').after(fwdEl);
+    }
   } catch {}
   if (forcePoll) {
     startPolling();