@zap-studio/webhooks 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @zap-studio/webhooks
+
+## 0.1.0
+
+### Minor Changes
+
+- 0d6254c: Initial public release of `@zap-studio/webhooks`.
+
+  - Introduces a schema-first webhook router with inferred payload types.
+  - Adds request verification support, including `createHmacVerifier`.
+  - Provides lifecycle hooks (`before`, `after`, `onError`) for cross-cutting concerns.
+  - Exposes framework-agnostic adapter contracts via `Adapter` and `BaseAdapter`.
+  - Includes comprehensive test coverage and documentation.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alexandre Trotel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# @zap-studio/webhooks
+
+Schema-first, type-safe webhook routing with signature verification support.
+
+Works with any validation library that implements [Standard Schema](https://github.com/standard-schema/standard-schema), including Zod, Valibot, and ArkType.
+
+## Why this package exists
+
+Webhook handlers usually repeat the same plumbing:
+
+- verify request authenticity
+- parse and validate payloads
+- route by event path
+- normalize success/error responses
+
+`@zap-studio/webhooks` isolates that plumbing so your handler code stays focused on business logic.
+
+Schemas are the source of truth, and payload types are inferred from them.
+
+## Install
+
+```bash
+pnpm add @zap-studio/webhooks
+```
+
+## Quickstart
+
+```ts
+import { createWebhookRouter } from "@zap-studio/webhooks";
+import { z } from "zod";
+
+const router = createWebhookRouter({
+  prefix: "/webhooks/",
+});
+
+router.register("payments/succeeded", {
+  schema: z.object({
+    id: z.string(),
+    amount: z.number().positive(),
+    currency: z.string().length(3),
+  }),
+  handler: async ({ payload, ack }) => {
+    // payload is inferred from schema
+    return ack({ status: 200, body: `processed ${payload.id}` });
+  },
+});
+```
+
+## GitHub webhook example
+
+```ts
+import { createWebhookRouter } from "@zap-studio/webhooks";
+import { createHmacVerifier } from "@zap-studio/webhooks/verify";
+import { z } from "zod";
+
+const router = createWebhookRouter({
+  verify: createHmacVerifier({
+    headerName: "x-hub-signature-256",
+    secret: process.env.GITHUB_WEBHOOK_SECRET!,
+  }),
+});
+
+router.register("github/push", {
+  schema: z.object({
+    ref: z.string(),
+    repository: z.object({
+      full_name: z.string(),
+    }),
+  }),
+  handler: async ({ payload, ack }) => {
+    console.log(`[github] ${payload.repository.full_name} ${payload.ref}`);
+    return ack();
+  },
+});
+```
+
+## Stripe webhook example
+
+```ts
+import Stripe from "stripe";
+import { createWebhookRouter } from "@zap-studio/webhooks";
+import { z } from "zod";
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
+
+const router = createWebhookRouter({
+  verify: async (req) => {
+    const signature = req.headers.get("stripe-signature");
+    if (!signature) {
+      throw new Error("Missing Stripe signature");
+    }
+
+    stripe.webhooks.constructEvent(
+      req.rawBody,
+      signature,
+      process.env.STRIPE_WEBHOOK_SECRET!
+    );
+  },
+});
+
+router.register("stripe/payment_intent.succeeded", {
+  schema: z.object({
+    id: z.string(),
+    object: z.literal("event"),
+    type: z.literal("payment_intent.succeeded"),
+  }),
+  handler: async ({ payload, ack }) => {
+    console.log(`[stripe] event ${payload.id} (${payload.type})`);
+    return ack({ status: 200 });
+  },
+});
+```
+
+## Lifecycle hooks
+
+Lifecycle hooks let you apply cross-cutting behavior without duplicating code in each handler:
+
+- `before`: run logic before verify/validation/handler (logging, tracing, rate-limit checks)
+- `after`: run logic after successful handler execution (metrics, audit logs)
+- `onError`: map thrown errors to consistent responses and centralize error reporting
+
+```ts
+const router = createWebhookRouter({
+  before: (req) => {
+    console.log("incoming", req.path);
+  },
+  after: (_req, res) => {
+    console.log("status", res.status);
+  },
+  onError: (error) => ({
+    status: 500,
+    body: { error: error.message },
+  }),
+});
+```
+
+## Verification helper
+
+`@zap-studio/webhooks/verify` exports `createHmacVerifier`, a small helper that builds a `verify` function for HMAC-signed webhook providers.
+
+- reads a signature from the header you choose
+- computes an HMAC from `req.rawBody`
+- compares signatures in constant time
+
+```ts
+import { createHmacVerifier } from "@zap-studio/webhooks/verify";
+
+const verify = createHmacVerifier({
+  headerName: "x-hub-signature-256",
+  secret: process.env.WEBHOOK_SECRET!,
+  algo: "sha256", // optional, defaults to sha256
+});
+```
+
+Use this when your provider uses standard HMAC signatures. For providers with custom signing formats, pass your own `verify` function.
+
+## Why `BaseAdapter` exists
+
+This package is framework-agnostic by design. It does not include Express/Next/Hono/Elysia adapters.
+
+`BaseAdapter` exists to help consumers implement adapters consistently:
+
+- you only implement `toNormalizedRequest` and `toFrameworkResponse`
+- `BaseAdapter` handles the common `handleWebhook()` flow
+- teams can reuse one adapter implementation across all webhook routes
+
+```ts
+import { BaseAdapter } from "@zap-studio/webhooks/adapters/base";
+import type { NormalizedRequest, NormalizedResponse } from "@zap-studio/webhooks/types";
+
+class MyHttpAdapter extends BaseAdapter {
+  async toNormalizedRequest(req: any): Promise<NormalizedRequest> {
+    return {
+      method: req.method,
+      path: req.url,
+      headers: new Headers(req.headers),
+      rawBody: req.rawBody,
+    };
+  }
+
+  async toFrameworkResponse(
+    res: any,
+    normalized: NormalizedResponse
+  ): Promise<any> {
+    res.statusCode = normalized.status;
+    res.end(
+      typeof normalized.body === "string"
+        ? normalized.body
+        : JSON.stringify(normalized.body)
+    );
+    return res;
+  }
+}
+```
+
+## License
+
+MIT

package/dist/adapters/base.d.mts

@@ -0,0 +1,58 @@
+import { NormalizedRequest, NormalizedResponse } from "../types/index.mjs";
+
+//#region src/adapters/base.d.ts
+
+/**
+ * Minimal framework adapter contract.
+ *
+ * Implement this when integrating the webhook router with an HTTP framework.
+ */
+interface Adapter {
+  /**
+   * Creates a framework handler that:
+   * 1. normalizes the incoming framework request
+   * 2. executes the webhook router
+   * 3. writes the normalized response back to the framework response
+   */
+  handleWebhook<TFrameworkReq = unknown, TFrameworkRes = unknown>(router: {
+    handle(req: NormalizedRequest): Promise<NormalizedResponse>;
+  }): (req: TFrameworkReq, res: TFrameworkRes) => Promise<void>;
+  /**
+   * Maps a normalized router response to the framework response object.
+   *
+   * @param frameworkRes - Framework-specific response object (e.g. `res`)
+   * @param res - Normalized response returned by the webhook router
+   */
+  toFrameworkResponse<TFrameworkRes = unknown>(frameworkRes: TFrameworkRes, res: NormalizedResponse): Promise<TFrameworkRes>;
+  /**
+   * Maps a framework request into the normalized request contract.
+   *
+   * The returned object must include `rawBody` to support signature verification.
+   *
+   * @param req - Framework-specific request object
+   */
+  toNormalizedRequest<TReq = unknown>(req: TReq): Promise<NormalizedRequest>;
+}
+/**
+ * Base adapter helper.
+ *
+ * Extend this class in consumers to keep framework integration boilerplate
+ * in one place while relying on the package router contract.
+ */
+declare abstract class BaseAdapter implements Adapter {
+  /** @inheritdoc */
+  abstract toNormalizedRequest<TReq = unknown>(req: TReq): Promise<NormalizedRequest>;
+  /** @inheritdoc */
+  abstract toFrameworkResponse<TFrameworkRes = unknown>(frameworkRes: TFrameworkRes, res: NormalizedResponse): Promise<TFrameworkRes>;
+  /**
+   * Shared adapter pipeline implementation.
+   *
+   * Most consumers only need to implement request/response mapping methods and
+   * can reuse this default orchestration.
+   */
+  handleWebhook<TFrameworkReq = unknown, TFrameworkRes = unknown>(router: {
+    handle(req: NormalizedRequest): Promise<NormalizedResponse>;
+  }): (req: TFrameworkReq, res: TFrameworkRes) => Promise<void>;
+}
+//#endregion
+export { Adapter, BaseAdapter };

package/dist/adapters/base.mjs

@@ -0,0 +1,25 @@
+//#region src/adapters/base.ts
+/**
+* Base adapter helper.
+*
+* Extend this class in consumers to keep framework integration boilerplate
+* in one place while relying on the package router contract.
+*/
+var BaseAdapter = class {
+	/**
+	* Shared adapter pipeline implementation.
+	*
+	* Most consumers only need to implement request/response mapping methods and
+	* can reuse this default orchestration.
+	*/
+	handleWebhook(router) {
+		return async (req, res) => {
+			const normalizedReq = await this.toNormalizedRequest(req);
+			const normalizedRes = await router.handle(normalizedReq);
+			await this.toFrameworkResponse(res, normalizedRes);
+		};
+	}
+};
+
+//#endregion
+export { BaseAdapter };

package/dist/index.d.mts

@@ -0,0 +1,68 @@
+import { AfterHook, BeforeHook, ErrorHook, InferSchemaOutput, NormalizedRequest, NormalizedResponse, RegisterOptions, SchemaRouteOptions, WebhookHandler } from "./types/index.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region src/index.d.ts
+interface WebhookRouterOptions {
+  /** Global hooks executed after successful route handler completion. */
+  after?: AfterHook | AfterHook[];
+  /** Global hooks executed before route-level hooks and verification. */
+  before?: BeforeHook | BeforeHook[];
+  /** Global error hook used to override the default `500` response. */
+  onError?: ErrorHook;
+  /** Required path prefix for all webhook routes. Defaults to `"/webhooks/"`. */
+  prefix?: string;
+  /** Optional request verification function (for signature checks, auth, etc.). */
+  verify?: (req: NormalizedRequest) => Promise<void> | void;
+}
+/**
+ * Main webhook router class.
+ *
+ * Register routes with typed schemas and call `handle` with a normalized request.
+ */
+declare class WebhookRouter<TMap = unknown> {
+  private readonly handlers;
+  private readonly verify?;
+  private readonly globalBeforeHooks;
+  private readonly globalAfterHooks;
+  private readonly globalErrorHook?;
+  private readonly prefix;
+  constructor(opts?: WebhookRouterOptions);
+  /**
+   * Register a webhook handler for a specific path.
+   *
+   * When a schema is provided, `payload` is inferred from the schema output type.
+   *
+   * @param path - Route path relative to configured prefix.
+   * @param handlerOrOptions - Handler function or schema-based registration options.
+   * @returns The same router instance with an updated internal route type map.
+   */
+  register<Path extends string, TSchema extends StandardSchemaV1<unknown, unknown>>(path: Path, handlerOrOptions: SchemaRouteOptions<TSchema>): WebhookRouter<TMap & Record<Path, InferSchemaOutput<TSchema>>>;
+  register<Path extends string, TPayload>(path: Path, handlerOrOptions: RegisterOptions<TPayload>): WebhookRouter<TMap & Record<Path, TPayload>>;
+  register<Path extends string>(path: Path, handlerOrOptions: WebhookHandler<unknown>): WebhookRouter<TMap & Record<Path, unknown>>;
+  /**
+   * Handles a normalized incoming webhook request.
+   *
+   * @param req - Normalized request object.
+   * @returns Normalized response for the adapter/framework layer.
+   */
+  handle(req: NormalizedRequest): Promise<NormalizedResponse>;
+  private normalizePath;
+  private runGlobalBeforeHooks;
+  private runRouteBeforeHooks;
+  private parseRequestBody;
+  private isErrorResponse;
+  private validatePayload;
+  private executeHandler;
+  private runRouteAfterHooks;
+  private runGlobalAfterHooks;
+  private handleError;
+}
+/**
+ * Factory helper for creating a webhook router instance.
+ *
+ * @param opts - Optional global router options.
+ * @returns A new webhook router.
+ */
+declare function createWebhookRouter(opts?: WebhookRouterOptions): WebhookRouter;
+//#endregion
+export { WebhookRouter, WebhookRouterOptions, createWebhookRouter };

package/dist/index.mjs

@@ -0,0 +1,156 @@
+import { standardValidate } from "@zap-studio/validation";
+
+//#region src/index.ts
+/**
+* Main webhook router class.
+*
+* Register routes with typed schemas and call `handle` with a normalized request.
+*/
+var WebhookRouter = class {
+	handlers = {};
+	verify;
+	globalBeforeHooks = [];
+	globalAfterHooks = [];
+	globalErrorHook;
+	prefix;
+	constructor(opts) {
+		this.prefix = opts?.prefix ?? "/webhooks/";
+		if (opts?.verify) this.verify = opts.verify;
+		if (opts?.before) this.globalBeforeHooks = Array.isArray(opts.before) ? opts.before : [opts.before];
+		if (opts?.after) this.globalAfterHooks = Array.isArray(opts.after) ? opts.after : [opts.after];
+		if (opts?.onError) this.globalErrorHook = opts.onError;
+	}
+	register(path, handlerOrOptions) {
+		if (typeof handlerOrOptions === "function") this.handlers[path] = { handler: handlerOrOptions };
+		else {
+			let beforeHooks;
+			if (handlerOrOptions.before) beforeHooks = Array.isArray(handlerOrOptions.before) ? handlerOrOptions.before : [handlerOrOptions.before];
+			let afterHooks;
+			if (handlerOrOptions.after) afterHooks = Array.isArray(handlerOrOptions.after) ? handlerOrOptions.after : [handlerOrOptions.after];
+			this.handlers[path] = {
+				handler: handlerOrOptions.handler,
+				schema: handlerOrOptions.schema,
+				before: beforeHooks,
+				after: afterHooks
+			};
+		}
+		return this;
+	}
+	/**
+	* Handles a normalized incoming webhook request.
+	*
+	* @param req - Normalized request object.
+	* @returns Normalized response for the adapter/framework layer.
+	*/
+	async handle(req) {
+		try {
+			const normalizedPath = this.normalizePath(req);
+			if (normalizedPath === null) return {
+				status: 404,
+				body: { error: "not found" }
+			};
+			const handlerEntry = this.handlers[normalizedPath];
+			if (!handlerEntry) return {
+				status: 404,
+				body: { error: "not found" }
+			};
+			await this.runGlobalBeforeHooks(req);
+			await this.runRouteBeforeHooks(req, handlerEntry.before);
+			if (this.verify) await this.verify(req);
+			const parsedJson = this.parseRequestBody(req);
+			const validationResult = await this.validatePayload(parsedJson, handlerEntry.schema);
+			if (this.isErrorResponse(validationResult)) return validationResult;
+			const response = await this.executeHandler(handlerEntry.handler, req, validationResult);
+			await this.runRouteAfterHooks(req, response, handlerEntry.after);
+			await this.runGlobalAfterHooks(req, response);
+			return response;
+		} catch (error) {
+			return this.handleError(error, req);
+		}
+	}
+	normalizePath(req) {
+		let pathname = req.path;
+		try {
+			pathname = new URL(req.path).pathname;
+		} catch {}
+		if (!pathname.startsWith(this.prefix)) return null;
+		pathname = pathname.slice(this.prefix.length - 1);
+		req.path = pathname;
+		return pathname.startsWith("/") ? pathname.slice(1) : pathname;
+	}
+	async runGlobalBeforeHooks(req) {
+		for (const hook of this.globalBeforeHooks) await hook(req);
+	}
+	async runRouteBeforeHooks(req, before) {
+		if (before) for (const hook of before) await hook(req);
+	}
+	parseRequestBody(req) {
+		try {
+			const parsed = JSON.parse(req.rawBody.toString());
+			req.json = parsed;
+			return parsed;
+		} catch {
+			return;
+		}
+	}
+	isErrorResponse(value) {
+		return typeof value === "object" && value !== null && "status" in value && typeof value.status === "number";
+	}
+	async validatePayload(parsedJson, schema) {
+		if (!schema) return parsedJson;
+		const result = await standardValidate(schema, parsedJson, false);
+		if (result.issues) return {
+			status: 400,
+			body: {
+				error: "validation failed",
+				issues: result.issues.map((issue) => ({
+					path: issue.path?.map((p) => typeof p === "object" && "key" in p ? String(p.key) : String(p)),
+					message: issue.message
+				}))
+			}
+		};
+		return result.value;
+	}
+	async executeHandler(handler, req, validatedPayload) {
+		return await handler({
+			req,
+			payload: validatedPayload,
+			ack: async (r) => ({
+				status: r?.status ?? 200,
+				body: r?.body ?? "ok",
+				headers: r?.headers
+			})
+		}) ?? {
+			status: 200,
+			body: "ok"
+		};
+	}
+	async runRouteAfterHooks(req, response, after) {
+		if (after) for (const hook of after) await hook(req, response);
+	}
+	async runGlobalAfterHooks(req, response) {
+		for (const hook of this.globalAfterHooks) await hook(req, response);
+	}
+	async handleError(error, req) {
+		if (this.globalErrorHook) {
+			const errorResponse = await this.globalErrorHook(error, req);
+			if (errorResponse) return errorResponse;
+		}
+		return {
+			status: 500,
+			body: { error: error instanceof Error ? error.message : "Internal server error" }
+		};
+	}
+};
+/**
+* Factory helper for creating a webhook router instance.
+*
+* @param opts - Optional global router options.
+* @returns A new webhook router.
+*/
+function createWebhookRouter(opts) {
+	return new WebhookRouter(opts);
+}
+
+//#endregion
+export { WebhookRouter, createWebhookRouter };

package/dist/types/index.d.mts

@@ -0,0 +1,92 @@
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region src/types/index.d.ts
+/** Framework-agnostic request shape consumed by the webhook router. */
+interface NormalizedRequest {
+  /** The headers of the request (e.g. { "Authorization": "Bearer token" }) */
+  headers: Headers;
+  /** The parsed JSON body of the request if applicable */
+  json?: unknown;
+  /** The HTTP method of the request */
+  method: Request["method"];
+  /** The route parameters of the request */
+  params?: Record<string, string>;
+  /** The path of the request you registered in the router (e.g. "payment", "subscription") */
+  path: string;
+  /** The query parameters of the request */
+  query?: Record<string, string | string[]>;
+  /** The raw body of the request (for signature) */
+  rawBody: Buffer;
+  /** The parsed text body of the request if applicable */
+  text?: string;
+}
+/** Framework-agnostic response shape returned by the webhook router. */
+interface NormalizedResponse<TBody = unknown> {
+  /** The body of the response */
+  body?: TBody;
+  /** The headers of the response */
+  headers?: Headers;
+  /** The HTTP status code of the response */
+  status: number;
+}
+/** Route registration options for a webhook handler. */
+interface RegisterOptions<T> {
+  /** Hooks that run after successful processing (before global after hooks) */
+  after?: AfterHook | AfterHook[];
+  /** Hooks that run before request processing (after global before hooks) */
+  before?: BeforeHook | BeforeHook[];
+  /** The handler function to process the webhook */
+  handler: WebhookHandler<T>;
+  /** Optional Standard Schema validator to validate the webhook payload */
+  schema?: StandardSchemaV1<unknown, T>;
+}
+/**
+ * Infers the output type from a Standard Schema instance.
+ *
+ * @typeParam TSchema - A Standard Schema type.
+ */
+type InferSchemaOutput<TSchema> = TSchema extends StandardSchemaV1<unknown, infer TOutput> ? TOutput : never;
+/**
+ * Route options where schema is required and handler payload is inferred.
+ *
+ * @typeParam TSchema - Schema used to infer handler payload type.
+ */
+type SchemaRouteOptions<TSchema extends StandardSchemaV1<unknown, unknown>> = Omit<RegisterOptions<InferSchemaOutput<TSchema>>, "schema"> & {
+  schema: TSchema;
+};
+interface RouteLike {
+  after?: AfterHook | AfterHook[];
+  before?: BeforeHook | BeforeHook[];
+  handler: WebhookHandler<unknown>;
+  schema: StandardSchemaV1<unknown, unknown>;
+}
+/**
+ * Applies schema-driven payload inference to each route entry.
+ *
+ * @typeParam TRoutes - Route dictionary keyed by webhook path.
+ */
+type SchemaRoutes<TRoutes extends Record<string, RouteLike>> = { [P in keyof TRoutes]: SchemaRouteOptions<TRoutes[P]["schema"]> };
+/** The webhook handler function, responsible for processing incoming webhook events. */
+type WebhookHandler<TPayload = unknown> = (ctx: {
+  req: NormalizedRequest;
+  payload: TPayload;
+  ack: (res?: Partial<NormalizedResponse>) => Promise<NormalizedResponse>;
+}) => Promise<NormalizedResponse | undefined> | NormalizedResponse | undefined;
+/** Maps route keys to their payload-specific webhook handlers. */
+type HandlerMap<TMap extends Record<string, unknown>> = { [P in keyof TMap]: WebhookHandler<TMap[P]> };
+/**
+ * Builds a webhook payload map from a schema-based route dictionary.
+ *
+ * @typeParam TRoutes - Route dictionary keyed by webhook path.
+ */
+type InferWebhookMapFromRoutes<TRoutes extends Record<string, RouteLike>> = { [P in keyof TRoutes]: InferSchemaOutput<TRoutes[P]["schema"]> };
+/** Verification function for incoming requests */
+type VerifyFn = (req: NormalizedRequest) => Promise<void> | void;
+/** Hook function that runs before request processing */
+type BeforeHook = (req: NormalizedRequest) => Promise<void> | void;
+/** Hook function that runs after successful request processing */
+type AfterHook = (req: NormalizedRequest, res: NormalizedResponse) => Promise<void> | void;
+/** Hook function that runs when an error occurs */
+type ErrorHook = (error: Error, req: NormalizedRequest) => Promise<NormalizedResponse | undefined> | NormalizedResponse | undefined;
+//#endregion
+export { AfterHook, BeforeHook, ErrorHook, HandlerMap, InferSchemaOutput, InferWebhookMapFromRoutes, NormalizedRequest, NormalizedResponse, RegisterOptions, SchemaRouteOptions, SchemaRoutes, VerifyFn, WebhookHandler };

package/dist/types/index.mjs

@@ -0,0 +1 @@
+export {  };

package/dist/utils/index.d.mts

@@ -0,0 +1,12 @@
+//#region src/utils/index.d.ts
+/**
+ * Compares two strings in constant time to prevent timing attacks.
+ *
+ * @example
+ * ```ts
+ * const isEqual = constantTimeEquals("string1", "string2"); // returns false
+ * ```
+ */
+declare function constantTimeEquals(a: string, b: string): boolean;
+//#endregion
+export { constantTimeEquals };

package/dist/utils/index.mjs

@@ -0,0 +1,18 @@
+//#region src/utils/index.ts
+/**
+* Compares two strings in constant time to prevent timing attacks.
+*
+* @example
+* ```ts
+* const isEqual = constantTimeEquals("string1", "string2"); // returns false
+* ```
+*/
+function constantTimeEquals(a, b) {
+	if (a.length !== b.length) return false;
+	let result = 0;
+	for (let i = 0; i < a.length; i += 1) result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+	return result === 0;
+}
+
+//#endregion
+export { constantTimeEquals };

package/dist/verify.d.mts

@@ -0,0 +1,49 @@
+import { VerifyFn } from "./types/index.mjs";
+import { BinaryLike, KeyObject } from "node:crypto";
+
+//#region src/verify.d.ts
+
+/**
+ * Creates an HMAC-based request verification function.
+ *
+ * The returned verifier reads the configured signature header, computes the
+ * expected HMAC from `req.rawBody`, and compares them in constant time.
+ *
+ * @note Uses Node.js `crypto` at runtime.
+ *
+ * @example
+ * ```ts
+ * import { createWebhookRouter } from "@zap-studio/webhooks";
+ * import { createHmacVerifier } from "@zap-studio/webhooks/verify";
+ * import { z } from "zod";
+ *
+ * const router = createWebhookRouter({
+ *   verify: createHmacVerifier({
+ *     headerName: "x-hub-signature-256",
+ *     secret: process.env.GITHUB_WEBHOOK_SECRET!,
+ *   }),
+ * });
+ *
+ * router.register("github/push", {
+ *   schema: z.object({ ref: z.string() }),
+ *   handler: async ({ ack }) => ack(),
+ * });
+ * ```
+ *
+ * @param options - HMAC verifier options.
+ * @param options.headerName - Header containing provider signature.
+ * @param options.secret - HMAC secret key.
+ * @param options.algo - Hash algorithm used for HMAC generation.
+ * @returns A verifier function compatible with router `verify`.
+ */
+declare function createHmacVerifier({
+  headerName,
+  secret,
+  algo
+}: {
+  headerName: string;
+  secret: BinaryLike | KeyObject;
+  algo?: string;
+}): VerifyFn;
+//#endregion
+export { createHmacVerifier };

package/dist/verify.mjs

@@ -0,0 +1,47 @@
+import { constantTimeEquals } from "./utils/index.mjs";
+
+//#region src/verify.ts
+const SIGNATURE_REGEX = /^sha256=/;
+/**
+* Creates an HMAC-based request verification function.
+*
+* The returned verifier reads the configured signature header, computes the
+* expected HMAC from `req.rawBody`, and compares them in constant time.
+*
+* @note Uses Node.js `crypto` at runtime.
+*
+* @example
+* ```ts
+* import { createWebhookRouter } from "@zap-studio/webhooks";
+* import { createHmacVerifier } from "@zap-studio/webhooks/verify";
+* import { z } from "zod";
+*
+* const router = createWebhookRouter({
+*   verify: createHmacVerifier({
+*     headerName: "x-hub-signature-256",
+*     secret: process.env.GITHUB_WEBHOOK_SECRET!,
+*   }),
+* });
+*
+* router.register("github/push", {
+*   schema: z.object({ ref: z.string() }),
+*   handler: async ({ ack }) => ack(),
+* });
+* ```
+*
+* @param options - HMAC verifier options.
+* @param options.headerName - Header containing provider signature.
+* @param options.secret - HMAC secret key.
+* @param options.algo - Hash algorithm used for HMAC generation.
+* @returns A verifier function compatible with router `verify`.
+*/
+function createHmacVerifier({ headerName, secret, algo = "sha256" }) {
+	return async (req) => {
+		const sig = req.headers.get(headerName.toLowerCase()) || "";
+		if (!sig) throw Object.assign(/* @__PURE__ */ new Error("missing signature"), { name: "SignatureError" });
+		if (!constantTimeEquals((await import("node:crypto")).createHmac(algo, secret).update(req.rawBody).digest("hex"), sig.replace(SIGNATURE_REGEX, ""))) throw Object.assign(/* @__PURE__ */ new Error("invalid signature"), { name: "SignatureError" });
+	};
+}
+
+//#endregion
+export { createHmacVerifier };

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@zap-studio/webhooks",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "homepage": "https://www.zapstudio.dev/packages/webhooks",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zap-studio/monorepo.git",
+    "directory": "packages/webhooks"
+  },
+  "description": "A lightweight, type-safe webhook router with Standard Schema validation, signature verification, and lifecycle hooks.",
+  "keywords": [
+    "webhooks",
+    "webhook router",
+    "type-safe",
+    "typescript",
+    "validation",
+    "schema",
+    "standard schema",
+    "zod",
+    "valibot",
+    "arktype",
+    "signature verification",
+    "lifecycle hooks",
+    "payload validation"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@standard-schema/spec": "^1.1.0",
+    "@zap-studio/validation": "0.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.2",
+    "@vitest/coverage-v8": "^4.0.15",
+    "tsdown": "^0.18.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18",
+    "zod": "^4.2.0",
+    "@zap-studio/vitest-config": "0.0.0",
+    "@zap-studio/typescript-config": "0.0.0",
+    "@zap-studio/tsdown-config": "0.0.0"
+  },
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./adapters/base": "./dist/adapters/base.mjs",
+    "./types": "./dist/types/index.mjs",
+    "./utils": "./dist/utils/index.mjs",
+    "./verify": "./dist/verify.mjs",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "scripts": {
+    "build": "tsdown --config tsdown.config.ts",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest --watch"
+  }
+}