webhookgate-sdk 1.0.1 → 1.0.2
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 +115 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# WebhookGate
|
|
2
|
+
|
|
3
|
+
WebhookGate guarantees **no duplicate webhook side effects**.
|
|
4
|
+
|
|
5
|
+
https://webhookgate.com
|
|
6
|
+
|
|
7
|
+
It does this by combining:
|
|
8
|
+
- **durable webhook intake and de-duplication** at the gateway layer, and
|
|
9
|
+
- a **consumer-side idempotency SDK** that makes duplicate side effects **structurally impossible** within the consumer.
|
|
10
|
+
|
|
11
|
+
WebhookGate sits in front of webhook consumers and ensures that each `(provider, eventId)` is **accepted exactly once**, even under retries, replays, or noisy providers - and that downstream effects are never duplicated when the consumer uses the SDK.
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## What WebhookGate guarantees (MVP)
|
|
16
|
+
|
|
17
|
+
WebhookGate provides a durable webhook “inbox” in front of your consumer.
|
|
18
|
+
|
|
19
|
+
### Gateway guarantees
|
|
20
|
+
|
|
21
|
+
- **Exactly-once acceptance** per `(provider, eventId)`
|
|
22
|
+
- **De-duplication at intake**: repeated deliveries of the same event are not re-accepted
|
|
23
|
+
- **Durable delivery jobs + transport retries**: downstream delivery is retried on network/transport failure
|
|
24
|
+
- **Deterministic Idempotency-Key propagation** on every downstream delivery
|
|
25
|
+
|
|
26
|
+
The gateway delivers events **at-least-once** downstream, always with the same
|
|
27
|
+
Idempotency-Key, even across retries, crashes, or restarts.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## Consumer SDK: No duplicate side effects
|
|
32
|
+
|
|
33
|
+
The consumer SDK converts delivery guarantees into **hard correctness**.
|
|
34
|
+
|
|
35
|
+
### What the SDK guarantees
|
|
36
|
+
|
|
37
|
+
- **At-most-once execution** of the handler per Idempotency-Key
|
|
38
|
+
- **Duplicate deliveries never re-run side effects**
|
|
39
|
+
- **Crash-safe behavior**: if the process crashes mid-handler, the handler is never re-entered (row remains processing)
|
|
40
|
+
- **Error behavior (terminal)**: if the handler throws, the idempotency row transitions to 'failed' and is never re-entered automatically
|
|
41
|
+
- **Transactional DB effects** for database operations performed via the provided db client
|
|
42
|
+
|
|
43
|
+
Once a key is successfully claimed, the handler will **never** be executed again — even if the process crashes, restarts, or receives the same event repeatedly.
|
|
44
|
+
|
|
45
|
+
> Result: side effects are never duplicated.
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## Exactly-once effects (clarified)
|
|
50
|
+
|
|
51
|
+
WebhookGate guarantees that your handler runs at most once per Idempotency-Key.
|
|
52
|
+
|
|
53
|
+
If your handler calls external systems (payments, email providers, APIs), those systems must respect idempotency keys to achieve end-to-end exactly-once effects across system boundaries.
|
|
54
|
+
|
|
55
|
+
This design deliberately favors **safety over re-execution**:
|
|
56
|
+
WebhookGate will never risk double-charging, double-emailing, or double-writing.
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## Install
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
npm install webhookgate-sdk
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
The SDK automatically creates the required idempotency tables on first use.
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## What the developer writes (locked API)
|
|
71
|
+
|
|
72
|
+
```js
|
|
73
|
+
import { idempotent } from "webhookgate-sdk";
|
|
74
|
+
|
|
75
|
+
app.post(
|
|
76
|
+
"/webhooks/stripe",
|
|
77
|
+
idempotent(async ({ event, db }) => {
|
|
78
|
+
await chargeCustomer(event); // never executed twice
|
|
79
|
+
await sendReceipt(event); // never executed twice
|
|
80
|
+
})
|
|
81
|
+
);
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## Proof: No duplicate side effects (60 seconds)
|
|
87
|
+
|
|
88
|
+
1. Start Postgres
|
|
89
|
+
2. Install dependencies
|
|
90
|
+
npm install
|
|
91
|
+
3. Start the consumer
|
|
92
|
+
npm run consumer
|
|
93
|
+
4. Start the gateway
|
|
94
|
+
npm run dev
|
|
95
|
+
5. Send a replay storm
|
|
96
|
+
npm run chaos -- evt_test_1
|
|
97
|
+
|
|
98
|
+
Result:
|
|
99
|
+
- Gateway receives 50 duplicate events
|
|
100
|
+
- Consumer executes the handler once
|
|
101
|
+
- /stats shows charges = 1
|
|
102
|
+
|
|
103
|
+
Crash test:
|
|
104
|
+
- Start consumer with CRASH_ONCE=true
|
|
105
|
+
- Re-run chaos
|
|
106
|
+
- Restart consumer
|
|
107
|
+
- Charges still = 1
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
## When you need production-grade durability
|
|
112
|
+
|
|
113
|
+
WebhookGate adds durable intake, replay protection, and operational safeguards for environments where local correctness is no longer sufficient.
|
|
114
|
+
|
|
115
|
+
Learn more at https://webhookgate.com
|