hmac-webhook

A tiny library + CLI to send signed webhook JSON payloads. Requests are authenticated by an HMAC-SHA256 signature of the raw JSON body.

Install

npm i hmac-webhook

Environment variables

Required:

HMAC_WEBHOOK_URL (webhook endpoint URL) HMAC_WEBHOOK_SECRET (shared HMAC secret)

Request format

POST JSON to HMAC_WEBHOOK_URL with headers:

content-type: application/json

x-webhook-signature: sha256=<hex> (HMAC over the exact JSON string body)

x-webhook-timestamp: <ms epoch>

Body example:

{
  "some-msg": "anything you want"
}

Server-side handling

Signature is over the exact JSON string sent (the “raw body”), which is what you should verify on the server side.

Hono middleware (receiver)

import { Hono } from "hono";
import { verifyWebhook } from "hmac-webhook";

const app = new Hono();

app.post(
  "/webhook/pages",
  verifyWebhook({
    secret: process.env.HMAC_WEBHOOK_SECRET,
    maxSkewMs: 5 * 60 * 1000, // optional replay mitigation
  }),
  async (c) => {
    const evt = c.get("webhookEvent"); // parsed JSON body
    // handle evt.event / evt.payload however you want
    return c.json({ ok: true });
  }
);

*Cloudflare Note: The middleware uses node:crypto + Buffer. Those are available in Workers only if you enable Node.js compatibility (nodejs_compat) and set an appropriate compatibility_date.