Debug webhook signature failures locally.
Figure out why webhook signature verification failed before your framework hides the evidence.
Documentation · npm · Latest release · Feedback · Contributing
HookLens is a local CLI for the annoying part of webhook debugging: the delivery reached your app, verification still failed, and your framework already changed the body you needed to inspect.
It captures the incoming request before your app/framework parses it, verifies it locally, stores the event, and lets you replay the delivery after you fix your app.
Important
HookLens now preserves exact raw request bytes for storage, verification, and replay. UTF-8/JSON text is derived only for display and --json output.
Requires Node.js 24 or newer.
npm install -g hooklenshooklens listen --verify github --secret ghsecret_xxx
hooklens list
hooklens inspect evt_abc123
hooklens replay evt_abc123 --to http://localhost:3000/webhookPoint your provider CLI, tunnel, or webhook source at http://127.0.0.1:4400.
Use HookLens when:
- the request reached your machine, but signature verification failed
- your framework parsed or re-serialized the body before verification
- you need the stored request and verification result, not a vague error line
- you want to replay the same event after changing middleware, secrets, or handler logic
It is not a tunnel, a hosted webhook inbox, or a replacement for provider delivery tooling.
- Getting Started for installation and first capture
- Examples for copy-paste Next.js, Express, and Fastify webhook setups
- Commands for the CLI reference
- Verification for failure codes and provider behavior
- Stripe signature failures
- GitHub signature mismatches
- Raw body mutation
- Contributing