🔍 hooklens

A webhook & HTTP request inspector in one Python file — standard library only, nothing to install.

Point any webhook, callback, or misbehaving HTTP client at it and watch every request appear live in a local dashboard: method, path, query, headers, body (JSON pretty-printed), with one-click copy as curl to replay it anywhere.

Like the hosted request-bin services — except it runs entirely on your machine, so the payloads you're debugging never leave localhost.

curl -O https://raw.githubusercontent.com/danielneustadter/hooklens/main/hooklens.py
python hooklens.py

The dashboard

Live via Server-Sent Events — requests appear the instant they land, no refresh:

And every capture logs to the terminal too:

Usage

python hooklens.py                  # dashboard on http://127.0.0.1:8787
python hooklens.py --port 9000      # different port
python hooklens.py --status 500     # reply 500 to every capture — test your retry logic
python hooklens.py --keep 1000      # bigger ring buffer (default 200)
python hooklens.py --open           # launch the dashboard in your browser
python hooklens.py --quiet          # no terminal logging

Then send it anything:

curl -X POST localhost:8787/pay/webhook \
  -H "Content-Type: application/json" \
  -d '{"event":"invoice.paid","amount":4200}'

Every method on every path is captured — only / (the dashboard) and /_hooklens/* (its API) are reserved.

What you get per request

• Method, path, query params, client IP, timestamp (ms precision)
• Every header, in original order
• Body up to 256 KB (JSON pretty-printed; binary shown as a base64 preview with size)
• Copy as curl — reconstructs the request as a shell-ready command
• Filter box, clear button, and a ring buffer so memory stays bounded

Programmatic API

The dashboard is just a client of a tiny JSON API you can script against:

Endpoint	Method	Purpose
/_hooklens/api/requests	GET	all captured requests as JSON
/_hooklens/api/events	GET	SSE stream of new captures
/_hooklens/api/clear	POST	empty the buffer
/_hooklens/api/health	GET	{"ok": true, "version": …}

curl -s localhost:8787/_hooklens/api/requests | python -m json.tool

Design notes

• Zero dependencies, one file. http.server + EventSource + a deque. If you have Python 3.9+, you have hooklens.
• Every capture responds with its id (X-Hooklens-Id header and JSON body), so the sender can correlate too.
• --status makes it a fault injector: point a webhook producer at hooklens, reply 500s, and watch how its retry/backoff really behaves.
• Local by default. Binds 127.0.0.1; use --host 0.0.0.0 deliberately if you want other machines (or a tunnel) to reach it.

Tests

Real end-to-end tests — they boot the server on an ephemeral port and hit it over HTTP:

python -m unittest discover -s tests -v

CI runs them on Linux, macOS, and Windows across Python 3.9 / 3.12 / 3.13.

License

MIT