Zyphe SDK – Webhook Signature Verification Middlewares

This package provides framework-agnostic and framework-specific webhook signature verification middlewares for Express, Fastify, Hono, and NestJS. It enables secure verification of incoming webhook requests from the Zyphe platform in your backend applications.

Installing package

If you want to use the middleware package outside of this monorepo, you can install it directly from npm:

pnpm install @zyphe-sdk/middlewares

Then import and use the middleware in your project as described in the Usage section below.

Usage: Verifying a Webhook Signature in Your Framework

This package provides ready-to-use middleware for popular Node.js frameworks. See below for usage in each supported framework.

Express

import express from "express";
import { expressWebhookSignatureVerifierMiddleware } from "@zyphe-sdk/middlewares/express";
import dotenv from "dotenv";

dotenv.config();
const app = express();
const port = 3001;
const secretHex = process.env.WEBHOOK_SECRET ?? "";

app.post(
  "/webhook",
  express.raw({ type: "application/json" }),
  expressWebhookSignatureVerifierMiddleware({
    secretHex,
    signatureHeader: "x-signature",
  }),
  (req, res) => {
    // At this point, the webhook signature has been verified
    // req.body contains the parsed JSON
    // req.rawBody contains the raw string (if exposeRawBody is true)
    res.json({ success: true, received: req.body });
  }
);

app.listen(port, () => {
  console.log(`Express server is running on http://localhost:${port}`);
});

Fastify

import Fastify from "fastify";
import fastifyWebhookSignatureVerifierPlugin from "@zyphe-sdk/middlewares/fastify";
import dotenv from "dotenv";

dotenv.config();
const secretHex = process.env.WEBHOOK_SECRET ?? "";

const fastify = Fastify({ logger: true });

await fastify.register(fastifyWebhookSignatureVerifierPlugin, {
  secretHex,
  signatureHeader: "x-signature",
});

fastify.post("/webhook", async (request, reply) => {
  // Signature verified, request.body and request.rawBody available
  return { success: true, received: request.body };
});

await fastify.listen({ port: 3001, host: "0.0.0.0" });

Hono

import { serve } from "@hono/node-server";
import { Hono } from "hono";
import { honoWebhookSignatureVerifierMiddleware } from "@zyphe-sdk/middlewares/hono";
import dotenv from "dotenv";

dotenv.config();
const secretHex = process.env.WEBHOOK_SECRET ?? "";

const app = new Hono();

app.post(
  "/webhook",
  honoWebhookSignatureVerifierMiddleware({
    secretHex,
    signatureHeader: "x-signature",
  }),
  async (c) => c.text("Hello Hono!")
);

serve({ fetch: app.fetch, port: 3001 });

NestJS

// app.module.ts
import { Module, MiddlewareConsumer } from "@nestjs/common";
import { NestjsWebhookSignatureVerifierMiddleware } from "@zyphe-sdk/middlewares/nestjs";
import { WebhookController } from "./webhook.controller";

@Module({
  controllers: [WebhookController],
})
export class AppModule {
  configure(consumer: MiddlewareConsumer) {
    const middleware = new NestjsWebhookSignatureVerifierMiddleware({
      secretHex: process.env.WEBHOOK_SECRET ?? "",
      signatureHeader: "x-signature",
    });
    consumer.apply(middleware.use).forRoutes("/webhook");
  }
}

// main.ts
import * as express from "express";
import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.use("/webhook", express.raw({ type: "application/json" }));
  await app.listen(3001);
}
bootstrap();

// webhook.controller.ts
import { Controller, Post, Req } from "@nestjs/common";
import { Request } from "express";

@Controller()
export class WebhookController {
  @Post("webhook")
  handleWebhook(@Req() req: Request) {
    // Signature verified, req.body and req.rawBody available
    return { success: true, received: req.body };
  }
}

Options

All middlewares accept the following options:

• secretHex (required): The hex-encoded secret key used to verify the signature
• signatureHeader (optional): The name of the header containing the signature (defaults to "x-signature")
• exposeRawBody (optional): Whether to make the raw body available on req.rawBody (defaults to true, if supported)
• onUnauthorized (optional): Custom function to handle unauthorized requests

Features

• Secure HMAC-SHA256 signature verification
• Easy integration with Express, Fastify, Hono, and NestJS
• Access to both parsed JSON body and raw body
• Customizable unauthorized handler
• TypeScript support out of the box

Made with ❤️ by Zyphe Inc