WebhookGate

WebhookGate guarantees no duplicate webhook side effects.

https://webhookgate.com

It does this by combining:

• durable webhook intake and de-duplication at the gateway layer, and
• a consumer-side idempotency SDK that makes duplicate side effects structurally impossible within the consumer.

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 ensures downstream effects are never duplicated when the consumer uses the SDK.

Documentation (problem-first)

If you want to understand why WebhookGate exists — not just how to use it — these documents explain the underlying failure modes and constraints:

• Why Webhook Retries Cause Duplicate Side Effects
  https://webhookgate.com/docs/why-retries-cause-duplicates

• Exactly-once Delivery Is a Myth
  https://webhookgate.com/docs/exactly-once-is-a-myth

• What a Real Guarantee Requires
  https://webhookgate.com/docs/what-a-real-guarantee-requires

These explain the distributed-systems constraints that make ad-hoc idempotency fragile, and the architectural boundaries required to make duplicate side effects impossible.

What WebhookGate guarantees (MVP)

WebhookGate provides a durable webhook “inbox” in front of your consumer.

Gateway guarantees

• Exactly-once acceptance per (provider, eventId)
• De-duplication at intake: repeated deliveries of the same event are not re-accepted
• Durable delivery jobs + transport retries: downstream delivery is retried on network/transport failure
• Deterministic Idempotency-Key propagation on every downstream delivery

The gateway delivers events at-least-once downstream, always with the same Idempotency-Key, even across retries, crashes, or restarts.

Consumer SDK: No duplicate side effects

The consumer SDK converts delivery guarantees into hard correctness.

What the SDK guarantees

• At-most-once execution of the handler per Idempotency-Key
• Duplicate deliveries never re-run side effects
• Crash-safe behavior: if the process crashes mid-handler, the handler is never re-entered (row remains processing)
• Error behavior (terminal): if the handler throws, the idempotency row transitions to 'failed' and is never re-entered automatically
• Transactional DB effects for database operations performed via the provided db client

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.

Result: side effects are never duplicated.

Exactly-once effects (clarified)

WebhookGate guarantees that your handler runs at most once per Idempotency-Key.

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.

This design deliberately favors safety over re-execution: WebhookGate will never risk double-charging, double-emailing, or double-writing.

Install

npm install webhookgate-sdk

The SDK automatically creates the required idempotency tables on first use.

What the developer writes (locked API)

import { idempotent } from "webhookgate-sdk";

app.post(
  "/webhooks/stripe",
  idempotent(async ({ event, db }) => {
    await chargeCustomer(event);   // never executed twice
    await sendReceipt(event);      // never executed twice
  })
);

Proof: No duplicate side effects (60 seconds)

1. Start Postgres
2. Install dependencies npm install
3. Start the consumer npm run consumer
4. Start the gateway npm run dev
5. Send a replay storm npm run chaos -- evt_test_1

Result:

• Gateway receives 50 duplicate events
• Consumer executes the handler once
• /stats shows charges = 1

Crash test:

• Start consumer with CRASH_ONCE=true
• Re-run chaos
• Restart consumer
• Charges still = 1

When you need production-grade durability

WebhookGate adds durable intake, replay protection, and operational safeguards for environments where local correctness is no longer sufficient.

Learn more:

• Overview: https://webhookgate.com
• Technical docs: https://webhookgate.com/docs