hooklens 1.0.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +38 -19
- package/dist/index.js +341 -205
- package/dist/index.js.map +1 -1
- package/package.json +6 -3
package/README.md
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
|
|
3
|
-
<img src="
|
|
3
|
+
<img src="https://ilia01.github.io/hooklens/logo.svg" alt="HookLens logo" width="88" height="88">
|
|
4
4
|
|
|
5
5
|
# HookLens
|
|
6
6
|
|
|
7
|
-
**
|
|
7
|
+
**Debug webhook signature failures locally.**
|
|
8
8
|
|
|
9
9
|
Figure out why webhook signature verification failed before your framework hides the evidence.
|
|
10
10
|
|
|
11
|
-
[Documentation](https://ilia01.github.io/hooklens/) · [npm](https://www.npmjs.com/package/hooklens) · [Latest release](https://github.com/Ilia01/hooklens/releases/latest) · [Contributing](./CONTRIBUTING.md)
|
|
11
|
+
[Documentation](https://ilia01.github.io/hooklens/) · [npm](https://www.npmjs.com/package/hooklens) · [Latest release](https://github.com/Ilia01/hooklens/releases/latest) · [Feedback](https://github.com/Ilia01/hooklens/issues/new/choose) · [Contributing](./CONTRIBUTING.md)
|
|
12
12
|
|
|
13
13
|
[](LICENSE)
|
|
14
14
|
[](https://github.com/Ilia01/hooklens/actions/workflows/ci.yml)
|
|
@@ -17,7 +17,17 @@ Figure out why webhook signature verification failed before your framework hides
|
|
|
17
17
|
|
|
18
18
|
---
|
|
19
19
|
|
|
20
|
-
HookLens is
|
|
20
|
+
HookLens is a local CLI for the annoying part of webhook debugging:
|
|
21
|
+
the delivery reached your app, verification still failed, and your framework already changed the body you needed to inspect.
|
|
22
|
+
|
|
23
|
+
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.
|
|
24
|
+
|
|
25
|
+
> [!IMPORTANT]
|
|
26
|
+
> HookLens now preserves exact raw request bytes for storage, verification, and replay. UTF-8/JSON text is derived only for display and `--json` output.
|
|
27
|
+
|
|
28
|
+
<p align="center">
|
|
29
|
+
<img src="https://ilia01.github.io/hooklens/hooklens-demo.gif" alt="HookLens demo showing capture, verification, listing, and replay from the terminal" width="980">
|
|
30
|
+
</p>
|
|
21
31
|
|
|
22
32
|
## Install
|
|
23
33
|
|
|
@@ -27,27 +37,36 @@ HookLens is an open-source CLI for local webhook debugging. It captures the raw
|
|
|
27
37
|
npm install -g hooklens
|
|
28
38
|
```
|
|
29
39
|
|
|
30
|
-
##
|
|
40
|
+
## The loop
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
hooklens listen --verify github --secret ghsecret_xxx
|
|
44
|
+
hooklens list
|
|
45
|
+
hooklens inspect evt_abc123
|
|
46
|
+
hooklens replay evt_abc123 --to http://localhost:3000/webhook
|
|
47
|
+
```
|
|
31
48
|
|
|
32
|
-
|
|
33
|
-
- [Commands](https://ilia01.github.io/hooklens/commands/)
|
|
34
|
-
- [Verification](https://ilia01.github.io/hooklens/verification/)
|
|
35
|
-
- [Forwarding](https://ilia01.github.io/hooklens/forwarding)
|
|
36
|
-
- [Architecture](https://ilia01.github.io/hooklens/architecture)
|
|
49
|
+
Point your provider CLI, tunnel, or webhook source at `http://127.0.0.1:4400`.
|
|
37
50
|
|
|
38
|
-
|
|
51
|
+
Use HookLens when:
|
|
39
52
|
|
|
40
|
-
-
|
|
41
|
-
-
|
|
53
|
+
- the request reached your machine, but signature verification failed
|
|
54
|
+
- your framework parsed or re-serialized the body before verification
|
|
55
|
+
- you need the stored request and verification result, not a vague error line
|
|
56
|
+
- you want to replay the same event after changing middleware, secrets, or handler logic
|
|
42
57
|
|
|
43
|
-
|
|
58
|
+
It is not a tunnel, a hosted webhook inbox, or a replacement for provider delivery tooling.
|
|
44
59
|
|
|
45
|
-
|
|
46
|
-
- Missing or malformed webhook signature headers
|
|
47
|
-
- Replaying captured events after middleware or secret changes
|
|
48
|
-
- Forwarding webhook traffic to a local target while keeping capture history
|
|
60
|
+
## Read Next
|
|
49
61
|
|
|
50
|
-
|
|
62
|
+
- [Getting Started](https://ilia01.github.io/hooklens/getting-started) for installation and first capture
|
|
63
|
+
- [Examples](./examples/README.md) for copy-paste Next.js, Express, and Fastify webhook setups
|
|
64
|
+
- [Commands](https://ilia01.github.io/hooklens/commands/) for the CLI reference
|
|
65
|
+
- [Verification](https://ilia01.github.io/hooklens/verification/) for failure codes and provider behavior
|
|
66
|
+
- [Stripe signature failures](https://ilia01.github.io/hooklens/verification/stripe-signature-failures)
|
|
67
|
+
- [GitHub signature mismatches](https://ilia01.github.io/hooklens/verification/github-signature-mismatch)
|
|
68
|
+
- [Raw body mutation](https://ilia01.github.io/hooklens/verification/raw-body-mutation)
|
|
69
|
+
- [Contributing](./CONTRIBUTING.md)
|
|
51
70
|
|
|
52
71
|
## License
|
|
53
72
|
|