Unified webhook verification and dispatch with normalized events and de-duplication.
npm install webhook-sentinelxUnified webhook verification and dispatch with normalized events and de-duplication. TypeScript-first, ESM+CJS, minimal dependencies.
Verify signatures from multiple providers (Stripe, Braintree, GitHub, Slack), normalize event shape, and prevent duplicates with an in-memory or Redis store.
---
- Signature verification for Stripe, Braintree, GitHub, Slack. Extensible providers.
- Normalized event shape: { id, source, type, createdAt, payload, raw, requestId? }.
- Dedup store options: in-memory by default or Redis as an optional peer dependency.
- Small dispatcher for ergonomic routing.
- Framework-friendly: Express, Next.js, or any Node HTTP server using raw body.
- Typed API and testable design with raw Buffer input.
---
``bash`
npm i webhook-sentinelxoptional at runtime only if you use these features
npm i braintree redis
braintree and redis are optional peer dependencies. Install them only if you use the Braintree provider or the Redis store in production.
Requirements: Node 18 or newer.
---
`ts
import express from "express";
import { createVerifier, MemoryStore, createDispatcher } from "webhook-sentinelx";
const app = express();
// Important: Stripe and Slack need the raw body
app.use("/webhooks", express.raw({ type: "/" }));
const verify = createVerifier({
stripe: { endpointSecret: process.env.STRIPE_WEBHOOK_SECRET! },
github: { secret: process.env.GH_WEBHOOK_SECRET! },
slack: { signingSecret: process.env.SLACK_SIGNING_SECRET! },
// Braintree uses its SDK and x-www-form-urlencoded body
braintree: {
merchantId: process.env.BT_MERCHANT_ID!,
publicKey: process.env.BT_PUBLIC_KEY!,
privateKey: process.env.BT_PRIVATE_KEY!,
environment: "sandbox", // or "production"
},
toleranceSec: 300, // anti replay window
});
const store = new MemoryStore({ ttlSec: 600 });
const on = createDispatcher();
on.on("stripe:payment_intent.succeeded", async (evt) => {
// your logic
});
app.post("/webhooks/:source", async (req, res) => {
try {
const raw = Buffer.isBuffer(req.body) ? req.body : Buffer.from(req.body);
const evt = await verify(req.params.source as any, req.headers as any, raw);
if (await store.seen(evt.id)) return res.sendStatus(202); // duplicate
await on.dispatch(${evt.source}:${evt.type}, evt);
res.sendStatus(200);
} catch (e: any) {
if (e.code === "SIGNATURE_VERIFICATION_FAILED") return res.status(400).send("bad signature");
if (e.code === "UNSUPPORTED_SOURCE") return res.status(404).send("unknown source");
if (e.code === "STALE_TIMESTAMP") return res.status(400).send("stale timestamp");
console.error(e);
res.sendStatus(500);
}
});
app.listen(3000, () => console.log("webhook-sentinelx listening on :3000"));
`
---
`ts
// pages/api/webhooks/[source].ts
import type { NextApiRequest, NextApiResponse } from "next";
import { createVerifier, MemoryStore } from "webhook-sentinelx";
export const config = { api: { bodyParser: false } }; // preserve raw body
const verify = createVerifier({
stripe: { endpointSecret: process.env.STRIPE_WEBHOOK_SECRET! },
});
const store = new MemoryStore({ ttlSec: 600 });
export default async function handler(req: NextApiRequest, res: NextApiResponse) {
if (req.method !== "POST") return res.status(405).end();
const source = req.query.source as any;
const chunks: Buffer[] = [];
for await (const c of req) chunks.push(Buffer.from(c));
const raw = Buffer.concat(chunks);
try {
const evt = await verify(source, req.headers as any, raw);
if (await store.seen(evt.id)) return res.status(202).end();
// handle evt
return res.status(200).end();
} catch (e: any) {
const code = e.code || "ERR";
const status =
code === "UNSUPPORTED_SOURCE" ? 404 : code === "SIGNATURE_VERIFICATION_FAILED" ? 400 : 500;
return res.status(status).send(code);
}
}
`
For App Router or Edge runtime make sure you can access the raw Request body as an ArrayBuffer and pass it as a Buffer to verify().
---
Config
`ts`
export type VerifierConfig = {
toleranceSec?: number; // anti replay window, default 300
stripe?: { endpointSecret: string };
braintree?: {
merchantId: string;
publicKey: string;
privateKey: string;
environment?: "sandbox" | "production";
};
github?: { secret: string };
slack?: { signingSecret: string };
};
NormalizedEvent
`ts`
export type NormalizedEvent = {
id: string;
source: "stripe" | "braintree" | "github" | "slack";
type: string;
createdAt: Date;
payload: unknown; // original parsed JSON or SDK object for Braintree
raw: Buffer; // raw request body
requestId?: string;
};
Errors thrown as WebhookSentinelxdError with code:
- UNSUPPORTED_SOURCE
-
-
- Stripe reads Stripe-Signature header and verifies HMAC SHA256 over t.rawBody. Requires raw body.x-hub-signature-256
- GitHub reads with sha256= prefix. HMAC SHA256 over raw body.x-slack-request-timestamp
- Slack reads and x-slack-signature. HMAC SHA256 over v0:{ts}:{raw}. Requires raw body.x-www-form-urlencoded
- Braintree consumes with bt_signature and bt_payload through the official SDK.
Raw body note: For HMAC verification providers do not JSON parse before verification. Pass the original bytes.
`ts
import { MemoryStore, RedisStore } from "webhook-sentinelx";
const memory = new MemoryStore({ ttlSec: 600 });
await memory.seen("event-id"); // false on first call, true afterwards within TTL
const redis = new RedisStore({ url: process.env.REDIS_URL!, keyPrefix: "webhook-sentinelx" });
await redis.seen("event-id");
`
`ts
import { createDispatcher } from "webhook-sentinelx";
const bus = createDispatcher();
bus.on("stripe:payment_intent.succeeded", (evt) => {
/.../
});
bus.on("github:push", (evt) => {
/.../
});
await bus.dispatch("stripe:payment_intent.succeeded", evt);
`
---
Published as dual ESM (.mjs) and CJS (.cjs) with typings.
Import examples:
`ts`
// ESM
import { createVerifier } from "webhook-sentinelx";
// CJS
const { createVerifier } = require("webhook-sentinelx");
---
`bash`
npm i -D typescript tsup vitest @types/node
npm run test
npm run build
---
- Use toleranceSec` to reject replayed events with stale timestamps.
- Always use HTTPS for webhook endpoints.
- Keep provider secrets in a secure manager or environment.
---
- More providers: Shopify, PayPal non Braintree, Plaid, Twilio, Notion.
- Pluggable retry or queue adapters such as SQS or Kafka.
- Delivery receipts and replay helpers.
---
MIT 2025