webhook-gate 1.0.3

package/.env.example

@@ -0,0 +1,7 @@
+PORT=3000
+WEBHOOK_SECRET=change-me
+DATABASE_URL=postgres://user:password@localhost:5432/webhookgate
+TARGET_URL=http://localhost:4000/webhooks/stripe
+RETRY_INTERVAL_MS=3000
+DELIVER_TIMEOUT_MS=5000
+INGEST_TOKEN=change-me

package/README.md

@@ -0,0 +1,115 @@
+# 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 that downstream effects are never duplicated when the consumer uses the SDK.
+
+---
+
+## 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
+
+```bash
+npm install webhookgate-sdk
+```
+
+The SDK automatically creates the required idempotency tables on first use.
+
+---
+
+## What the developer writes (locked API)
+
+```js
+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 at https://webhookgate.com

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "webhook-gate",
+  "version": "1.0.3",
+  "type": "module",
+  "main": "src/index.js",
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "nodemon src/index.js",
+    "consumer": "node src/consumer-demo.js",
+    "chaos": "node scripts/chaos.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/webhookgate/webhook-gate.git"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/webhookgate/webhook-gate/issues"
+  },
+  "homepage": "https://github.com/webhookgate/webhook-gate#readme",
+  "description": "",
+  "dependencies": {
+    "better-sqlite3": "^12.5.0",
+    "dotenv": "^17.2.3",
+    "express": "^5.2.1",
+    "pg": "^8.16.3",
+    "stripe": "^20.1.0"
+  },
+  "devDependencies": {
+    "nodemon": "^3.1.11"
+  }
+}

package/packages/sdk/idempotent.js

@@ -0,0 +1,142 @@
+import { Pool } from "pg";
+
+const pool = new Pool({
+  host: process.env.PGHOST,
+  port: process.env.PGPORT ? Number(process.env.PGPORT) : undefined,
+  database: process.env.PGDATABASE,
+  user: process.env.PGUSER,
+  password: process.env.PGPASSWORD,
+  ssl: process.env.PGSSL === "true" ? { rejectUnauthorized: false } : undefined,
+});
+
+let _readyPromise = null;
+
+async function ensureTables() {
+  if (_readyPromise) return _readyPromise;
+
+  _readyPromise = (async () => {
+    await pool.query(`
+      CREATE TABLE IF NOT EXISTS webhook_idempotency (
+        idempotency_key TEXT PRIMARY KEY,
+        status TEXT NOT NULL CHECK (status IN ('processing','done','failed')),
+        created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+        completed_at TIMESTAMPTZ
+      );
+    `);
+
+    await pool.query(`
+      CREATE TABLE IF NOT EXISTS demo_charges (
+        id BIGSERIAL PRIMARY KEY,
+        idempotency_key TEXT NOT NULL UNIQUE,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+      );
+    `);
+  })();
+
+  return _readyPromise;
+}
+
+function getIdempotencyKey(req) {
+  // Primary: what our gateway sends
+  const k = req.get("Idempotency-Key") || req.get("idempotency-key");
+  return k ? String(k).trim() : "";
+}
+
+/**
+ * Locked API:
+ * app.post("/webhooks/stripe", idempotent(async ({ req, event, db }) => {}))
+ *
+ * Guarantees:
+ * - first time key seen: handler runs
+ * - any repeat of same key: handler does NOT run (returns 200)
+ * - crash or error mid-handler: key transitions to 'failed' and is never re-run
+ */
+export function idempotent(handler) {
+  return async function idempotentMiddleware(req, res) {
+    await ensureTables();
+
+    const key = getIdempotencyKey(req);
+
+    if (!key) {
+      return res.status(400).json({
+        ok: false,
+        error: "Missing Idempotency-Key header",
+      });
+    }
+
+    // IMPORTANT: the SDK assumes req.body already contains the parsed event
+    const event = req.body;
+
+    const client = await pool.connect();
+    let inTxn = false;
+    try {
+      // Atomic "claim"
+      // If it inserts: we own execution.
+      // If it conflicts: someone already claimed (or finished) => skip.
+      const claimed = await client.query(
+        `
+        INSERT INTO webhook_idempotency (idempotency_key, status)
+        VALUES ($1, 'processing')
+        ON CONFLICT (idempotency_key) DO NOTHING
+        RETURNING idempotency_key
+        `,
+        [key]
+      );
+
+      if (claimed.rowCount === 0) {
+        // Already seen => do nothing (exactly-once effects)
+        return res.status(200).json({ ok: true, deduped: true });
+      }
+
+      // 2) Transaction boundary for DB effects inside handler
+      await client.query("BEGIN");
+      inTxn = true;
+
+      // Run user handler
+      await handler({ req, res, event, db: client });
+
+      // Mark done
+      await client.query(
+        `
+        UPDATE webhook_idempotency
+        SET status='done', completed_at=now()
+        WHERE idempotency_key=$1
+        `,
+        [key]
+      );
+
+      await client.query("COMMIT");
+      inTxn = false;
+
+      // If handler already wrote to res, don't double-send.
+      if (!res.headersSent) {
+        return res.status(200).json({ ok: true, deduped: false });
+      }
+    } catch (err) {
+      // best-effort rollback if handler started a txn
+      try {
+        if (inTxn) await client.query("ROLLBACK");
+      } catch (_) {}
+
+      // Optional: mark failed (still prevents reruns, which is the contract you chose)
+      try {
+        await client.query(
+          `
+          UPDATE webhook_idempotency
+          SET status='failed', completed_at=now()
+          WHERE idempotency_key=$1 AND status='processing'
+          `,
+          [key]
+        );
+      } catch (_) {
+        // ignore secondary failure
+      }
+
+      if (!res.headersSent) {
+        return res.status(500).json({ ok: false, error: err?.message || String(err) });
+      }
+    } finally {
+      client.release();
+    }
+  };
+}

package/packages/sdk/index.js

@@ -0,0 +1,2 @@
+// packages/sdk/index.js
+export { idempotent } from "./idempotent.js";

package/packages/sdk/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "webhookgate-sdk",
+  "version": "1.0.1",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "license": "ISC",
+  "dependencies": {
+    "pg": "^8.16.3"
+  }
+}

package/scripts/chaos.js

@@ -0,0 +1,72 @@
+// scripts/chaos.js
+import "dotenv/config";
+
+const GATEWAY = process.env.GATEWAY_URL || "http://localhost:3000/ingest";
+const TOKEN = process.env.INGEST_TOKEN || "";
+const CONSUMER = process.env.CONSUMER_URL || "http://localhost:4000";
+
+async function postIngest({ provider, eventId, payload }) {
+  const resp = await fetch(GATEWAY, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      ...(TOKEN ? { "X-WebhookGate-Token": TOKEN } : {}),
+    },
+    body: JSON.stringify({ provider, eventId, payload }),
+  });
+  const json = await resp.json().catch(() => ({}));
+  return { status: resp.status, json };
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+async function getStats() {
+  const resp = await fetch(`${CONSUMER}/stats`);
+  const json = await resp.json().catch(() => ({}));
+  return { status: resp.status, json };
+}
+
+async function main() {
+  const provider = "stripe";
+  const eventId = process.argv[2] || "evt_test_1";
+
+  // Burst duplicates concurrently
+  const N = 50;
+  const results = await Promise.all(
+    Array.from({ length: N }).map((_, i) =>
+      postIngest({
+        provider,
+        eventId,
+        payload: { n: i, ts: Date.now() },
+      })
+    )
+  );
+
+  const firstTimeCount = results.filter((r) => r.json?.firstTime).length;
+  console.log({ sent: N, firstTimeCount, sample: results[0] });
+
+  // Fetch consumer stats (give gateway a moment to deliver + retry loop to run)
+  let stats;
+  for (let attempt = 1; attempt <= 10; attempt++) {
+    stats = await getStats().catch(() => null);
+
+    if (stats && stats.status === 200) {
+      // If your consumer increments charges, this prints the proof
+      console.log({ consumerStats: stats.json, attempt });
+      break;
+    }
+
+    await sleep(250);
+  }
+
+  if (!stats || stats.status !== 200) {
+    console.log({ consumerStats: null, error: "Failed to fetch /stats from consumer" });
+  }
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/scripts/git-hooks/pre-commit

@@ -0,0 +1,6 @@
+#!/bin/sh
+if git diff --cached --name-only | grep -Eiq '(^|/)node_modules/'; then
+  echo "ERROR: node_modules is staged. Aborting commit."
+  exit 1
+fi
+exit 0

package/src/config.js

@@ -0,0 +1,18 @@
+export const PORT = process.env.PORT ? Number(process.env.PORT) : 3000;
+
+// Optional shared secret for webhook auth later
+export const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET || "";
+
+// Where to forward accepted webhooks
+export const TARGET_URL = process.env.TARGET_URL || "";
+
+// Retry loop tuning (MVP defaults)
+export const RETRY_INTERVAL_MS = process.env.RETRY_INTERVAL_MS
+  ? Number(process.env.RETRY_INTERVAL_MS)
+  : 3000;
+
+export const DELIVER_TIMEOUT_MS = process.env.DELIVER_TIMEOUT_MS
+  ? Number(process.env.DELIVER_TIMEOUT_MS)
+  : 5000;
+
+export const INGEST_TOKEN = process.env.INGEST_TOKEN || "";

package/src/consumer-demo.js

@@ -0,0 +1,60 @@
+import "dotenv/config";
+import express from "express";
+import { Pool } from "pg";
+import { idempotent } from "./idempotent.js";
+
+const app = express();
+app.use(express.json());
+
+let crashedOnce = false;
+
+const statsPool = new Pool({
+  host: process.env.PGHOST,
+  port: process.env.PGPORT ? Number(process.env.PGPORT) : undefined,
+  database: process.env.PGDATABASE,
+  user: process.env.PGUSER,
+  password: process.env.PGPASSWORD,
+  ssl: process.env.PGSSL === "true" ? { rejectUnauthorized: false } : undefined,
+});
+
+async function chargeCustomer({ db, key }) {
+  await db.query(
+    `INSERT INTO demo_charges (idempotency_key) VALUES ($1)
+     ON CONFLICT (idempotency_key) DO NOTHING`,
+    [key]
+  );
+}
+async function sendReceipt(_) {}
+
+app.post(
+  "/webhooks/stripe",
+  idempotent(async ({ event, db, req }) => {
+    const key = (req.get("Idempotency-Key") || req.get("idempotency-key") || "").trim();
+
+    await chargeCustomer({ db, key });
+
+    if (process.env.CRASH_ONCE === "true" && !crashedOnce) {
+      crashedOnce = true;
+      console.log("[consumer] crashing after charge (CRASH_ONCE=true)");
+      process.exit(1);
+    }
+
+    await sendReceipt(event);
+  })
+);
+
+app.get("/stats", async (_, res) => {
+  try {
+    const r = await statsPool.query(`SELECT COUNT(*)::int AS charges FROM demo_charges`);
+    return res.json({ charges: r.rows[0].charges });
+  } catch (e) {
+    return res.status(500).json({ ok: false, error: e?.message || String(e) });
+  }
+});
+
+process.on("SIGINT", async () => {
+  await statsPool.end().catch(() => {});
+  process.exit(0);
+});
+
+app.listen(4000, () => console.log("consumer demo on 4000"));

package/src/db.js

@@ -0,0 +1,108 @@
+import Database from "better-sqlite3";
+import fs from "fs";
+import path from "path";
+
+const dbPath = process.env.SQLITE_PATH || "./data/webhookgate.sqlite";
+
+// ensure ./data exists
+fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+
+const db = new Database(dbPath);
+
+// WAL helps reliability under concurrent access
+db.pragma("journal_mode = WAL");
+
+db.exec(`
+  CREATE TABLE IF NOT EXISTS receipts (
+    provider    TEXT NOT NULL,
+    event_id    TEXT NOT NULL,
+    received_at INTEGER NOT NULL,
+    PRIMARY KEY (provider, event_id)
+  );
+
+  CREATE TABLE IF NOT EXISTS deliveries (
+    provider     TEXT NOT NULL,
+    event_id     TEXT NOT NULL,
+    target_url   TEXT NOT NULL,
+    payload_json TEXT NOT NULL,
+
+    status       TEXT NOT NULL DEFAULT 'pending', -- pending | delivered | failed
+    attempts     INTEGER NOT NULL DEFAULT 0,
+    last_error   TEXT,
+    created_at   INTEGER NOT NULL,
+    updated_at   INTEGER NOT NULL,
+    delivered_at INTEGER,
+
+    PRIMARY KEY (provider, event_id, target_url)
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_deliveries_status_updated
+    ON deliveries(status, updated_at);
+`);
+
+export function tryMarkReceived(provider, eventId) {
+  const stmt = db.prepare(`
+    INSERT INTO receipts (provider, event_id, received_at)
+    VALUES (?, ?, ?)
+  `);
+
+  try {
+    stmt.run(provider, eventId, Date.now());
+    return { firstTime: true };
+  } catch (err) {
+    const code = String(err && err.code);
+    if (code.startsWith("SQLITE_CONSTRAINT")) {
+      return { firstTime: false };
+    }
+    throw err;
+  }
+}
+
+export function upsertDelivery({ provider, eventId, targetUrl, payload }) {
+  const now = Date.now();
+  const payloadJson = JSON.stringify(payload ?? null);
+
+  // If delivery already exists, keep the original payload (don’t overwrite).
+  const stmt = db.prepare(`
+    INSERT INTO deliveries (provider, event_id, target_url, payload_json, status, attempts, created_at, updated_at)
+    VALUES (?, ?, ?, ?, 'pending', 0, ?, ?)
+    ON CONFLICT(provider, event_id, target_url) DO NOTHING
+  `);
+
+  stmt.run(provider, eventId, targetUrl, payloadJson, now, now);
+}
+
+export function getPendingDeliveries(limit = 25) {
+  const stmt = db.prepare(`
+    SELECT provider, event_id as eventId, target_url as targetUrl, payload_json as payloadJson, attempts
+    FROM deliveries
+    WHERE status = 'pending'
+    ORDER BY updated_at ASC
+    LIMIT ?
+  `);
+  return stmt.all(limit);
+}
+
+export function markDelivered(provider, eventId, targetUrl) {
+  const now = Date.now();
+  const stmt = db.prepare(`
+    UPDATE deliveries
+    SET status='delivered', delivered_at=?, updated_at=?
+    WHERE provider=? AND event_id=? AND target_url=?
+  `);
+  stmt.run(now, now, provider, eventId, targetUrl);
+}
+
+export function markAttemptFailed(provider, eventId, targetUrl, message) {
+  const MAX = Number(process.env.MAX_ATTEMPTS || 25);
+  const now = Date.now();
+  const stmt = db.prepare(`
+    UPDATE deliveries
+    SET attempts = attempts + 1,
+        last_error = ?,
+        status = CASE WHEN attempts + 1 >= ? THEN 'failed' ELSE status END,
+        updated_at = ?
+    WHERE provider=? AND event_id=? AND target_url=? AND status='pending'
+  `);
+  stmt.run(String(message || "unknown error"), MAX, now, provider, eventId, targetUrl);
+}

package/src/idempotent.js

@@ -0,0 +1,143 @@
+// src/idempotent.js
+import { Pool } from "pg";
+
+const pool = new Pool({
+  host: process.env.PGHOST,
+  port: process.env.PGPORT ? Number(process.env.PGPORT) : undefined,
+  database: process.env.PGDATABASE,
+  user: process.env.PGUSER,
+  password: process.env.PGPASSWORD,
+  ssl: process.env.PGSSL === "true" ? { rejectUnauthorized: false } : undefined,
+});
+
+let _readyPromise = null;
+
+async function ensureTables() {
+  if (_readyPromise) return _readyPromise;
+
+  _readyPromise = (async () => {
+    await pool.query(`
+      CREATE TABLE IF NOT EXISTS webhook_idempotency (
+        idempotency_key TEXT PRIMARY KEY,
+        status TEXT NOT NULL CHECK (status IN ('processing','done','failed')),
+        created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+        completed_at TIMESTAMPTZ
+      );
+    `);
+
+    await pool.query(`
+      CREATE TABLE IF NOT EXISTS demo_charges (
+        id BIGSERIAL PRIMARY KEY,
+        idempotency_key TEXT NOT NULL UNIQUE,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+      );
+    `);
+  })();
+
+  return _readyPromise;
+}
+
+function getIdempotencyKey(req) {
+  // Primary: what our gateway sends
+  const k = req.get("Idempotency-Key") || req.get("idempotency-key");
+  return k ? String(k).trim() : "";
+}
+
+/**
+ * Locked API:
+ * app.post("/webhooks/stripe", idempotent(async ({ req, event, db }) => {}))
+ *
+ * Guarantees:
+ * - first time key seen: handler runs
+ * - any repeat of same key: handler does NOT run (returns 200)
+ * - crash or error mid-handler: key transitions to 'failed' and is never re-run
+ */
+export function idempotent(handler) {
+  return async function idempotentMiddleware(req, res) {
+    await ensureTables();
+
+    const key = getIdempotencyKey(req);
+
+    if (!key) {
+      return res.status(400).json({
+        ok: false,
+        error: "Missing Idempotency-Key header",
+      });
+    }
+
+    // IMPORTANT: the SDK assumes req.body already contains the parsed event
+    const event = req.body;
+
+    const client = await pool.connect();
+    let inTxn = false;
+    try {
+      // Atomic "claim"
+      // If it inserts: we own execution.
+      // If it conflicts: someone already claimed (or finished) => skip.
+      const claimed = await client.query(
+        `
+        INSERT INTO webhook_idempotency (idempotency_key, status)
+        VALUES ($1, 'processing')
+        ON CONFLICT (idempotency_key) DO NOTHING
+        RETURNING idempotency_key
+        `,
+        [key]
+      );
+
+      if (claimed.rowCount === 0) {
+        // Already seen => do nothing (exactly-once effects)
+        return res.status(200).json({ ok: true, deduped: true });
+      }
+
+      // 2) Transaction boundary for DB effects inside handler
+      await client.query("BEGIN");
+      inTxn = true;
+
+      // Run user handler
+      await handler({ req, res, event, db: client });
+
+      // Mark done
+      await client.query(
+        `
+        UPDATE webhook_idempotency
+        SET status='done', completed_at=now()
+        WHERE idempotency_key=$1
+        `,
+        [key]
+      );
+
+      await client.query("COMMIT");
+      inTxn = false;
+
+      // If handler already wrote to res, don't double-send.
+      if (!res.headersSent) {
+        return res.status(200).json({ ok: true, deduped: false });
+      }
+    } catch (err) {
+      // best-effort rollback if handler started a txn
+      try {
+        if (inTxn) await client.query("ROLLBACK");
+      } catch (_) {}
+
+      // Optional: mark failed (still prevents reruns, which is the contract you chose)
+      try {
+        await client.query(
+          `
+          UPDATE webhook_idempotency
+          SET status='failed', completed_at=now()
+          WHERE idempotency_key=$1 AND status='processing'
+          `,
+          [key]
+        );
+      } catch (_) {
+        // ignore secondary failure
+      }
+
+      if (!res.headersSent) {
+        return res.status(500).json({ ok: false, error: err?.message || String(err) });
+      }
+    } finally {
+      client.release();
+    }
+  };
+}

package/src/index.js

@@ -0,0 +1,127 @@
+import "dotenv/config";
+import express from "express";
+import {
+  PORT,
+  TARGET_URL,
+  RETRY_INTERVAL_MS,
+  DELIVER_TIMEOUT_MS,
+  INGEST_TOKEN,
+} from "./config.js";
+import {
+  tryMarkReceived,
+  upsertDelivery,
+  getPendingDeliveries,
+  markDelivered,
+  markAttemptFailed,
+} from "./db.js";
+
+const app = express();
+app.use(express.json());
+
+app.get("/health", (_, res) => res.json({ ok: true }));
+
+function withTimeout(ms) {
+  const controller = new AbortController();
+  const t = setTimeout(() => controller.abort(), ms);
+  return { signal: controller.signal, cancel: () => clearTimeout(t) };
+}
+
+async function deliverOne({ provider, eventId, targetUrl, payload }) {
+  const key = `${provider}:${eventId}:${targetUrl}`;
+
+  const { signal, cancel } = withTimeout(DELIVER_TIMEOUT_MS);
+  try {
+    const resp = await fetch(targetUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Idempotency-Key": key,
+        "X-WebhookGate-Provider": provider,
+        "X-WebhookGate-EventId": eventId,
+      },
+      body: JSON.stringify(payload ?? null),
+      signal,
+    });
+
+    if (!resp.ok) {
+      // Semantic failure in consumer; do NOT retry.
+      console.log(`[downstream-non2xx] ${key} ${resp.status} ${resp.statusText}`);
+    }
+
+    markDelivered(provider, eventId, targetUrl);
+    console.log(`[deliver-ok] ${key}`);
+    return true;
+
+  } catch (err) {
+    markAttemptFailed(provider, eventId, targetUrl, err?.message || String(err));
+    console.log(`[deliver-fail] ${key} ${err?.message || String(err)}`);
+    return false;
+  } finally {
+    cancel();
+  }
+}
+
+// MVP: send { provider, eventId, payload }
+app.post("/ingest", async (req, res) => {
+  const provider = String(req.body?.provider || "");
+  const eventId = String(req.body?.eventId || "");
+  const payload = req.body?.payload;
+
+  if (INGEST_TOKEN) {
+    const t = String(req.get("X-WebhookGate-Token") || "");
+    if (t !== INGEST_TOKEN) {
+      return res.status(401).json({ ok: false, error: "Unauthorized" });
+    }
+  }
+
+  if (!provider || !eventId) {
+    return res.status(400).json({ ok: false, error: "provider and eventId are required" });
+  }
+
+  if (!TARGET_URL) {
+    return res.status(500).json({ ok: false, error: "TARGET_URL is not set" });
+  }
+
+  const { firstTime } = tryMarkReceived(provider, eventId);
+
+  if (!firstTime) {
+    console.log(`[dedupe] ${provider} ${eventId}`);
+    return res.status(200).json({ ok: true, firstTime: false });
+  }
+
+  console.log(`[accept] ${provider} ${eventId}`);
+
+  // Store delivery job durably so retries are possible
+  upsertDelivery({ provider, eventId, targetUrl: TARGET_URL, payload });
+
+  // Best-effort immediate delivery attempt
+  const delivered = await deliverOne({ provider, eventId, targetUrl: TARGET_URL, payload });
+
+  // Even if not delivered yet, we return 200 to stop webhook retry storms.
+  return res.status(200).json({ ok: true, firstTime: true, delivered });
+});
+
+// Simple in-process retry loop (MVP)
+let draining = false;
+async function drainOnce() {
+  if (draining) return;
+  draining = true;
+
+  try {
+    const jobs = getPendingDeliveries(25);
+    for (const j of jobs) {
+      const payload = JSON.parse(j.payloadJson);
+      await deliverOne({ provider: j.provider, eventId: j.eventId, targetUrl: j.targetUrl, payload });
+    }
+  } finally {
+    draining = false;
+  }
+}
+
+setInterval(() => {
+  drainOnce().catch((e) => console.log(`[drain-error] ${e?.message || String(e)}`));
+}, RETRY_INTERVAL_MS);
+
+app.listen(PORT, () => {
+  console.log(`WebhookGate listening on ${PORT}`);
+});