Debugging Local Web Services with ngrok’s HTTP Request Inspection & Replay

Desired Outcome

Use ngrok’s built‑in request inspection and replay feature to capture real traffic sent to your local server and re‑send selected requests for debugging or testing.

Prerequisites

• ngrok installed and authenticated with an account that supports request inspection (paid plans only).
• A local HTTP server running on a known port (e.g., localhost:8080).
• Network connectivity to ngrok’s public endpoint.
• Administrative or root privileges if you need to bind to ports < 1024.

Step‑by‑Step Procedure

1. Start the HTTP Tunnel

   Open a terminal and run:

   ngrok http 8080
   

   ngrok will output a public URL (e.g., https://abcd1234.ngrok.io) and a dashboard address (e.g., http://127.0.0.1:4040). The tunnel status should turn green indicating it’s live.

2. Access the ngrok Web UI

   Navigate to the dashboard URL (usually http://127.0.0.1:4040) or the public URL with the /ui path: https://abcd1234.ngrok.io/ui. The UI is where you’ll see the Request Inspection tab.

3. Inspect Incoming Requests

   Click the Request Inspection tab. Each row shows the request method, path, status code, and timestamp. The list is refreshed automatically as traffic arrives.

4. Replay a Selected Request

   Locate the request you want to replay, then click the Replay button next to it. ngrok will forward the exact same HTTP request—including headers, query strings, and body—to your local server.

   Note: Replay is only available on paid plans. If the button is disabled, verify your plan supports this feature.

5. Verify the Replay

   Check your local server logs or endpoint response to confirm the request was received. For example, if your server logs all POST bodies, you should see the same payload twice.

   In a web browser, you can also visit the endpoint URL (e.g., https://abcd1234.ngrok.io/api/test) after replaying and observe the response.

Expected Checks

• The ngrok tunnel status is green and the dashboard loads without errors.
• Recent traffic appears in the Request Inspection list within a few seconds of hitting your local endpoint.
• The Replay button is enabled for at least one request.
• After clicking Replay, the local server logs a second entry or returns a second response.
• The ngrok dashboard shows an incremented count in the Replayed traffic metric.

Recovery Options

• Tunnel fails to start – Verify ngrok is authenticated: ngrok authtoken <token>. Restart the tunnel. Check firewall rules that might block outbound connections.
• No requests in the inspection list – Ensure the local server is reachable at the specified port and that the request path matches the ngrok public URL. Confirm your plan supports request inspection.
• Replay button disabled – Upgrade to a paid ngrok plan or use the --inspect flag if available.
• Replay fails to reach the server – Inspect server logs for connection refusals. Verify the server is still running and listening on the correct port.
• When using sensitive data, remember that replayed requests will hit the live server, potentially causing side effects. Run the tunnel in a controlled test environment if possible.

Practical Example

Assume you have a Flask app listening on localhost:5000. You want to replay a POST request that created a user but did not persist due to a bug.

# Start the tunnel
ngrok http 5000

# In another terminal, trigger the original request
curl -X POST https://abcd1234.ngrok.io/users -H "Content-Type: application/json" -d '{"name":"Alice"}'

# Go to http://127.0.0.1:4040/ui, find the request in Request Inspection, click Replay
# Verify Flask logs show a second POST to /users

Limitations & Best Practices

• Replay may trigger destructive actions (e.g., deleting data). Use a sandbox or mock server.
• The free ngrok plan limits inspection to 200 requests/hour and disables replay. Upgrade if you need higher limits.
• Keep your ngrok auth token secure; avoid hard‑coding it in scripts or version control.
• Replay preserves the original client IP header (X-Forwarded-For), which may affect rate limits or security rules on the local server.

Conclusion

ngrok’s request inspection and replay feature is a quick way to re‑exercise real traffic against a local server, making debugging faster and more accurate. By following the steps above, you can capture problematic requests and replay them safely in a controlled environment.