Skip to content

HookLensDebug webhook signatures locally.

The webhook reached your app but verification failed. HookLens captures the raw request, tells you what went wrong, and replays the event after you fix it.

Terminal demo

hooklens

What the output actually means.

Instead of a generic “invalid signature” error, HookLens returns one of these codes so you know where to look.

missing_headerThe expected signature header was not in the request.
malformed_headerThe header was present but did not match the expected format.
expired_timestampThe timestamp in the signature fell outside the tolerance window.
signature_mismatchThe header parsed correctly but the computed digest did not match.
body_mutatedThe secret is likely correct, but middleware parsed and re-serialized the body bytes.

Three commands. That's the whole loop.

01

Listen

Start a local server that captures and optionally verifies incoming webhooks.

hooklens listen
02

Inspect

View the stored event: headers, body, and the specific failure code.

hooklens inspect <id>
03

Replay

Resend the same method, headers, and body to your app after fixing the issue.

hooklens replay <id>

What HookLens is not.

HookLens handles local verification debugging after the webhook reaches your machine. Everything before that is someone else's job.

  • Not a tunnel. Use ngrok, Cloudflare Tunnel, or your provider CLI.
  • Not a hosted webhook inbox. Events are stored locally in SQLite.
  • Not a replacement for Stripe CLI or GitHub delivery tools.

Start from the provider that failed.

Everything else.

Released under the MIT License.