@portable/webhooks

Verifies and signs webhooks from Standard Webhooks senders (Svix, Resend, Clerk and others), Stripe, GitHub and Slack, and from any other sender that signs with HMAC-SHA256 once you describe its headers. Runs in browsers, Cloudflare Workers, Deno, Bun and Node 24+.

Replaces standardwebhooks, the Webhook class in svix, Stripe's constructEvent and constructEventAsync in stripe, @octokit/webhooks-methods and the request verification in @slack/bolt.

npm install @portable/webhooks

import * as Webhooks from '@portable/webhooks';
 
export default {
  async fetch(
    request: Request,
    env: { STRIPE_WEBHOOK_SECRET: string },
  ) {
    try {
      const { body } = await Webhooks.verify(request, {
        scheme: Webhooks.stripe,
        secret: env.STRIPE_WEBHOOK_SECRET,
      });
      const event = JSON.parse(body);
      // handle event
      return new Response(null, { status: 204 });
    } catch (error) {
      if (error instanceof Webhooks.VerificationError) {
        return new Response(null, { status: 400 });
      }
      throw error;
    }
  },
};

verify reads the raw bytes of the request body and computes the HMAC over them, so a body parser, a re-serialized JSON object or a lost byte order mark can't break the signature. It then returns the body as text for you to parse: Slack slash commands and some GitHub deliveries are form-encoded, not JSON.

In tests, sign returns the headers the provider would send:

const body = JSON.stringify({ id: 'evt_1', object: 'event' });
const headers = await Webhooks.sign(body, {
  scheme: Webhooks.stripe,
  secret: 'whsec_test',
});
const response = await worker.fetch(
  new Request('https://example.com', { method: 'POST', body, headers }),
  env,
);

API

verify throws a TypeError or RangeError for a mistake in the call rather than in the request. An empty secret, a Standard Webhooks secret that isn't base64, or an invalid now throws a RangeError. A scheme that isn't a scheme object, or a body that isn't a string or Uint8Array, such as a parsed JSON object, throws a TypeError.

The result's id is the delivery id from webhook-id, svix-id or x-github-delivery. Store it to drop a redelivered webhook, which the timestamp check can't catch inside the tolerance.

Options

Schemes

A header may carry several signatures (Standard Webhooks separates them with spaces, Stripe repeats v1=), and one match is enough. Standard Webhooks v1a (ed25519) signatures and GitHub's SHA-1 x-hub-signature header are ignored.

Other senders

A scheme is an object of plain functions: parse reads the signatures (as bytes), timestamp and id from the headers, payload returns what the sender signs, headers writes the headers for sign, and the optional key turns a string secret into key bytes. verify and sign do everything else the same way for every scheme: the HMAC, the length check and constant-time compare, several secrets and the timestamp tolerance. For a sender that signs with HMAC-SHA256, write its scheme:

import * as Webhooks from '@portable/webhooks';
 
const utf8 = new TextEncoder();
const seconds = (date: Date) =>
  String(Math.floor(date.getTime() / 1000));
const toHex = (bytes: Uint8Array) =>
  Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join(
    '',
  );
 
// Acme sends `acme-timestamp: <seconds>` and `acme-signature: <hex>`, the HMAC-SHA256 of
// `{timestamp}.{body}`.
const acme: Webhooks.Scheme = {
  parse(headers) {
    const signature = headers.get('acme-signature');
    const timestamp = headers.get('acme-timestamp');
    if (!signature || !timestamp) {
      throw new Webhooks.VerificationError({
        code: 'missing-header',
        message: 'Missing Acme headers',
      });
    }
    if (!/^[\da-f]{64}$/.test(signature) || !/^\d+$/.test(timestamp)) {
      throw new Webhooks.VerificationError({
        code: 'malformed-header',
        message: 'Malformed Acme headers',
      });
    }
    return {
      signatures: [
        Uint8Array.from(signature.match(/../g)!, (byte) =>
          parseInt(byte, 16),
        ),
      ],
      timestamp: new Date(Number(timestamp) * 1000),
    };
  },
  payload: ({ timestamp, body }) =>
    new Uint8Array([
      ...utf8.encode(`${seconds(timestamp!)}.`),
      ...body,
    ]),
  headers: ({ signature, timestamp }) => ({
    'acme-timestamp': seconds(timestamp),
    'acme-signature': toHex(signature),
  }),
};
 
const { body } = await Webhooks.verify(request, {
  scheme: acme,
  secret: env.ACME_SECRET,
});

This package won't add schemes beyond these four. The built-in ones in src/schemes.ts are written the same way.

Crypto

verify and sign compute HMAC-SHA256 with WebCrypto.hmac from @portable/web-crypto, which calls crypto.subtle, so the package needs no dependency outside @portable/* for it. WebCrypto is async, but verify already has to await the request body. WebCrypto.hmac caches imported keys for up to 16 secrets, because importKey takes about two thirds of each HMAC on Node and half in Chromium, and the cache made a verification about 2.9× faster on Node.

On Node, verify is about 3 times faster with @noble/hashes than with WebCrypto's HMAC. To verify many webhooks on Node, install @noble/hashes and pass it as hmac:

import { hmac } from '@noble/hashes/hmac.js';
import { sha256 } from '@noble/hashes/sha2.js';
import * as Webhooks from '@portable/webhooks';
 
const { body } = await Webhooks.verify(request, {
  scheme: Webhooks.github,
  secret,
  hmac: (_hash, key, data) => hmac(sha256, key, data),
});

Types

Why use this over the provider libraries

One package verifies all four schemes, and any other HMAC-SHA256 sender through a scheme object. It computes the HMAC with crypto.subtle and no dependency, so you don't install the stripe, svix or @slack/bolt SDK for one function, and it runs in any JavaScript runtime.

• The HMAC covers the body bytes as received. Stripe and standardwebhooks decode the body as UTF-8 and encode it again, so a body with a byte order mark or invalid UTF-8 fails verification.
• The timestamp tolerance applies in both directions, and tolerance: 0 allows no skew. Stripe and Slack accept a timestamp any distance in the future, and Stripe's tolerance: 0 turns the check off.
• A GitHub signature needs the sha256= prefix and exactly 64 hex digits. The web build of @octokit/webhooks-methods accepts a bare signature and skips characters that aren't hex.
• Signature lengths are compared before the constant-time compare, so a truncated signature fails. Svix's Rust library let one pass (CVE-2024-21491).
• Stripe's constructEvent takes tolerance in seconds, and verify takes it in milliseconds, so Stripe's 300 becomes tolerance: 300_000. Stripe's tolerance: 0 turns the check off, and here 0 requires the exact second and Infinity turns the check off.
• Stripe's generateTestHeaderString takes timestamp in seconds. sign takes the time as now, a Date or a Temporal.Instant.
• A timestamp must be an integer number of seconds. standardwebhooks and Stripe read 123abc as 123 with parseInt.
• @octokit/webhooks-methods's verify returns false for a bad signature. Webhooks.verify throws instead.
• Stripe and standardwebhooks parse the JSON body for you. verify returns the text, because Slack and GitHub can send form-encoded bodies.
• verify doesn't reject Stripe's thin events (v2.core.event), because it doesn't look inside the body.

Performance

Operations per second from pnpm bench, higher is better, in Node 24.22.0, on Intel(R) Xeon(R) Processor @ 2.10GHz (4 cores). A dash means the library has no equivalent.

Sizes cover the imports in the usage example, or the equivalent imports of each library, bundled for the browser by scripts/bundle-size.ts. Runtime dependencies count every package installed with the published package. A library that uses Node built-ins needs polyfills in a browser and the nodejs_compat flag in Cloudflare Workers.

The second column passes @noble/hashes as hmac, as the Crypto section shows. WebCrypto HMAC is fast in browsers and Workers, so you can keep the default there.