🛡️ webhookshield

Unified, zero-dependency, edge-compatible webhook signature verification library for Node.js and TypeScript.

webhookshield is a lightweight security utility that provides a single, unified API to verify webhook signatures across popular SaaS platforms. By using native runtime cryptography, it eliminates the need to install heavy official SDKs (like @stripe/stripe-js or @clerk/backend), resulting in a smaller bundle size and zero external dependencies.

Key Features

• ⚡ Sub-10ms Edge Execution: Zero dependencies and fully optimized for Edge runtimes (Cloudflare Workers, Vercel Edge, Bun, Lagon) as well as traditional Node.js.
• 🔒 Hardened Security: Utilizes cryptographic constant-time comparison algorithms (crypto.timingSafeEqual) to completely block timing attacks.
• 🛠️ Multi-Provider Support: Verify signatures for Stripe, GitHub, Clerk, Resend, Shopify, and Lemon Squeezy in one library.
• 📦 Native TypeScript Support: Prepackaged with type definitions (index.d.ts) for developer autocompletion.
• ⏳ Replay Attack Guards: Automated timestamp drift verification checks (with customizable tolerances).

Supported Providers

| Provider | Signature Format | Header Key | Replay Protection | | :--- | :--- | :--- | :--- | | Stripe | HMAC-SHA256 (Hex) | stripe-signature | ✅ Yes (5m Tolerance) | | GitHub | HMAC-SHA256 (Hex) | x-hub-signature-256 | ❌ No | | Clerk / Svix | HMAC-SHA256 (Base64) | svix-signature | ✅ Yes (5m Tolerance) | | Resend | HMAC-SHA256 (Base64) | svix-signature | ✅ Yes (5m Tolerance) | | Shopify | HMAC-SHA256 (Base64) | x-shopify-hmac-sha256 | ❌ No | | Lemon Squeezy | HMAC-SHA256 (Hex) | x-signature | ❌ No |

Installation

Install via your preferred package manager:

npm install webhookshield
# or
yarn add webhookshield
# or
pnpm add webhookshield
# or
bun add webhookshield

Quick Start Examples

1. Stripe Webhooks

const { verify } = require('webhookshield');

const isValid = verify('stripe', {
  payload: req.rawBody, // Must be the raw request string
  signature: req.headers['stripe-signature'],
  secret: process.env.STRIPE_WEBHOOK_SECRET
});

if (!isValid) {
  return res.status(400).send('Webhook signature verification failed');
}

2. Clerk (Svix) Webhooks

const { verify } = require('webhookshield');

const isValid = verify('clerk', {
  payload: req.rawBody,
  signature: req.headers['svix-signature'],
  secret: process.env.CLERK_WEBHOOK_SECRET,
  svixId: req.headers['svix-id'],
  svixTimestamp: req.headers['svix-timestamp']
});

3. GitHub Webhooks

const { verify } = require('webhookshield');

const isValid = verify('github', {
  payload: req.rawBody,
  signature: req.headers['x-hub-signature-256'],
  secret: process.env.GITHUB_WEBHOOK_SECRET
});

Contributing

We welcome community contributions! If you want to add signature support for a new provider:

1. Fork and clone the repository: git clone https://github.com/Ezeko/webhookshield.git
2. Add your provider logic in src/providers.js
3. Write automated unit assertions in tests/index.test.js
4. Run tests locally: npm test

Please read our Contributing Guide to understand linting rules and PR submission procedures.

License

MIT © Ezekiel Adejobi