webhook-signature

webhook-signature

Unified webhook signature verification for multiple providers (Stripe, Paddle, GitHub, Slack, and more). One API, framework-agnostic core. Use in Node.js with Express, Fastify, Next.js, or any server.

Install

npm install webhook-signature

Quick example

import { verify } from 'webhook-signature';

const result = verify('stripe', {
  rawBody: requestBody,
  headers: { 'stripe-signature': signatureHeader },
}, { secret: process.env.STRIPE_WEBHOOK_SECRET });

if (!result.ok) {
  console.error(result.error);
  return;
}
// Proceed with handling the webhook

Supported providers

Provider	Option key	Notes
Stripe	stripe	Use endpoint secret (whsec_...), maxAgeSeconds recommended
Paddle	paddle	HMAC-SHA256, timestamp in header
GitHub	github	X-Hub-Signature-256
Shopify	shopify	X-Shopify-Hmac-SHA256
Slack	slack	X-Slack-Signature, timestamp header
Lemon Squeezy	lemon_squeezy	X-Signature
Square	square	Secret is hex-encoded
Zoom	zoom	Same pattern as Slack
Dropbox	dropbox	X-Dropbox-Signature
Figma	figma	figma-signature
Linear	linear	linear-signature
Intercom	intercom	HMAC-SHA1, X-Hub-Signature
Zendesk	zendesk	Timestamp + body, base64

Getting the raw body

Verification uses the raw request body (before JSON parsing). If your framework parses the body, the signature will not match.

Express

Use express.raw() for the webhook route only:

import express from 'express';
import { expressWebhookVerifier } from 'webhook-signature';

const app = express();

// Webhook route: raw body first, then verifier, then your handler
app.post(
  '/webhooks/stripe',
  express.raw({ type: 'application/json' }),
  expressWebhookVerifier('stripe', { secret: process.env.STRIPE_WEBHOOK_SECRET, maxAgeSeconds: 300 }),
  (req, res) => {
    // req.body is the raw Buffer here; parse if needed
    res.sendStatus(200);
  }
);

// Other routes can use express.json() as usual
app.use(express.json());

Next.js (App Router)

Read the raw body with request.text() or request.arrayBuffer() before verifying:

import { verify } from 'webhook-signature';
import { NextResponse } from 'next/server';

export async function POST(request: Request) {
  const rawBody = await request.text();
  const headers: Record<string, string> = {};
  request.headers.forEach((v, k) => { headers[k] = v; });
  const result = verify('stripe', { rawBody, headers }, { secret: process.env.STRIPE_WEBHOOK_SECRET! });
  if (!result.ok) return NextResponse.json({ error: result.error }, { status: 401 });
  // ...
}

Generic Node.js (IncomingMessage)

If you have access to the raw body buffer (e.g. you pushed chunks into an array and concatenated), pass it and the headers map to verify().

API

• verify(provider, payload, options) → { ok: true } | { ok: false, error: string }
• getSupportedProviders() → ProviderId[]
• expressWebhookVerifier(provider, options) → Express middleware
• fastifyWebhookVerifier(provider, options) → Fastify preHandler (use with fastify-raw-body or similar for raw body)

License

MIT