webhook-hmac-kit

Lightweight, production-ready toolkit for signing and verifying webhook requests using HMAC-SHA256.
Implements a Stripe-style security model with timestamp validation and replay protection.

Correct webhook security. No magic. No footguns.
Used in production systems handling financial & operational webhooks
(Salesforce, Workato-style integrations)

• Zero runtime dependencies (Node.js built-in crypto)
• Dual format: ESM + CJS, fully tree-shakeable
• TypeScript-first with strict types
• Constant-time signature comparison

Install

npm install webhook-hmac-kit

Quick Start

import { signWebhook, verifyWebhook } from 'webhook-hmac-kit';
import crypto from 'node:crypto';

// --- Sender side ---
const rawBody = JSON.stringify({ event: 'payment.completed', amount: 4999 });

const { signature } = signWebhook({
  secret: 'whsec_your_secret_key',
  payload: rawBody,                  // exact bytes you send
  timestamp: Math.floor(Date.now() / 1000),
  nonce: crypto.randomUUID(),
});

// Send signature, timestamp, and nonce as headers

// --- Receiver side ---
const result = await verifyWebhook({
  secret: 'whsec_your_secret_key',
  payload: rawBody,                  // exact bytes received
  signature: req.headers['x-webhook-signature'],
  timestamp: Number(req.headers['x-webhook-timestamp']),
  nonce: req.headers['x-webhook-nonce'],
});

// result.valid === true (throws on failure)

API Reference

signWebhook(options): SignWebhookResult

Synchronous. Computes an HMAC-SHA256 signature over a canonical string.

| Parameter | Type | Required | Description | | ----------- | -------- | -------- | ---------------------------------------- | | secret | string | Yes | Shared secret key | | payload | string | Yes | Raw request body (exact bytes) | | timestamp | number | Yes | Unix timestamp (seconds) | | nonce | string | Yes | Unique request identifier | | version | string | No | Canonical version prefix (default: v1) |

Returns:

{ signature: string } // hex-encoded

verifyWebhook(options): Promise<VerifyWebhookResult>

Async. Verifies signature, timestamp, and optional replay protection.

| Parameter | Type | Required | Description | | ---------------- | ------------------------------------- | -------- | ---------------------------------------- | | secret | string | Yes | Shared secret key | | payload | string | Yes | Raw request body | | signature | string | Yes | Hex-encoded signature | | timestamp | number | Yes | Unix timestamp (seconds) | | nonce | string | Yes | Unique request identifier | | tolerance | number | No | Max age in seconds (default: 300) | | nonceValidator | (nonce: string) => Promise<boolean> | No | Return false if nonce was already seen |

Returns { valid: true } on success. Throws a typed error on failure.

Error Handling

All verification failures throw typed errors for precise handling.

| Error Class | Code | Recommended HTTP Status | | ----------------------- | --------------------------- | ----------------------- | | WebhookSignatureError | WEBHOOK_SIGNATURE_INVALID | 401 Unauthorized | | WebhookTimestampError | WEBHOOK_TIMESTAMP_EXPIRED | 400 Bad Request | | WebhookNonceError | WEBHOOK_NONCE_REPLAYED | 409 Conflict |

import {
  verifyWebhook,
  WebhookTimestampError,
  WebhookSignatureError,
  WebhookNonceError,
} from 'webhook-hmac-kit';

try {
  await verifyWebhook({ ... });
} catch (err) {
  if (err instanceof WebhookTimestampError) {
    // Too old or too far in the future
  } else if (err instanceof WebhookSignatureError) {
    // Tampered payload or wrong secret
  } else if (err instanceof WebhookNonceError) {
    // Replay attack / duplicate delivery
  }
}

Canonical String

All signatures are computed over:

{version}:{timestamp}:{nonce}:{payload}

Example (v1):

v1:1700000000:nonce_abc123:{"event":"payment.completed","amount":4999}

The payload is included verbatim — no encoding, escaping, or normalization.

Why Raw Body Matters

HMAC signs exact bytes. Parsing JSON breaks signatures.

const raw = '{ "amount": 4999, "currency": "usd" }';

JSON.stringify(JSON.parse(raw));
// {"amount":4999,"currency":"usd"} ← different bytes

signWebhook({ payload: raw });                        // correct
signWebhook({ payload: JSON.stringify(JSON.parse(raw)) }); // ❌ mismatch

Always verify first, parse second.

Common Webhook Security Mistakes

1. Using === for signature comparison → Vulnerable to timing attacks. This library uses crypto.timingSafeEqual.

2. No timestamp validation → Captured requests can be replayed forever.

3. No nonce checking → Requests can be replayed within the tolerance window.

4. Parsing body before verification → Breaks signatures due to re-serialization.

5. Logging secrets → Log canonical strings or hashes, never secrets.

Platform Examples

Express.js (Receiver)

import express from 'express';
import { verifyWebhook, WebhookError } from 'webhook-hmac-kit';

const app = express();

app.post(
  '/webhook',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    try {
      await verifyWebhook({
        secret: process.env.WEBHOOK_SECRET!,
        payload: req.body.toString('utf-8'),
        signature: req.headers['x-webhook-signature'],
        timestamp: Number(req.headers['x-webhook-timestamp']),
        nonce: req.headers['x-webhook-nonce'],
      });

      const event = JSON.parse(req.body.toString('utf-8'));
      res.sendStatus(200);
    } catch (err) {
      if (err instanceof WebhookError) {
        res.status(401).json({ error: err.code });
      } else {
        res.sendStatus(500);
      }
    }
  }
);

Redis Nonce Validator (Replay Protection)

nonceValidator: async (nonce) => {
  const key = `webhook:nonce:${nonce}`;
  const exists = await redis.exists(key);
  if (exists) return false;
  await redis.set(key, '1', 'EX', 300);
  return true;
};

Sending Webhooks (Salesforce-style)

import { signWebhook } from 'webhook-hmac-kit';
import crypto from 'node:crypto';

const payload = JSON.stringify({ event: 'record.updated', id: '001xx000003DGbX' });
const timestamp = Math.floor(Date.now() / 1000);
const nonce = crypto.randomUUID();

const { signature } = signWebhook({
  secret: 'whsec_your_secret',
  payload,
  timestamp,
  nonce,
});

Why not JWT?

JWTs are designed for authentication, not signing arbitrary HTTP payloads.

Webhook signatures must:

• Sign exact raw bytes
• Avoid JSON canonicalization issues
• Be cheap to verify

HMAC is simpler, safer, and battle-tested for webhook integrity.

Test Vectors

All vectors use secret whsec_test_secret_key_1234567890 and version v1.

| Payload | Timestamp | Nonce | Expected Signature | | --------------------------------------------- | ------------ | ----------------- | ------------------------------------------------------------------ | | {"event":"payment.completed","amount":4999} | 1700000000 | nonce_abc123 | dfa71af8832a81f0b996c3411de0b29f02a9292256a24ecf363465d3285bdc6b | | (empty) | 1700000000 | nonce_empty001 | 96771f2cf8576c2154f7fbcdcea8840087539ca78ce3a5b91539cce7354b0d05 | | {"name":"Héllo Wörld","emoji":"🚀"} | 1700000000 | nonce_unicode01 | 0907a577eb997d1d8d355051bd50efcb73af1075d04353c437e931b3f92f4f95 |

Security Considerations

• Constant-time comparison
• Replay protection via timestamp + nonce
• Secret rotation supported at integration layer
• HTTPS required (integrity ≠ confidentiality)
• Apply payload size limits at HTTP layer

License

MIT