@zap-studio/webhooks 0.4.0 → 1.1.0

package/CHANGELOG.md

@@ -1,10 +1,36 @@
-## @zap-studio/webhooks@0.4.0
+# Changelog
 
-### Rework the package on Web API `Request`/`Response` (breaking)
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0]
+
+### Added
+
+`WebhookRouter` (and `createWebhookRouter(...)`) gain an optional `logger?: Logger` option (from `@zap-studio/logger`). When provided, it logs each delivery attempt and handler dispatch at `debug`, and verification failures and unmatched routes at `warn`. Omitting it keeps zero logging overhead. See [Logging](https://www.zapstudio.dev/webhooks/logging).
+
+## [1.0.0]
+
+### Changed
+
+`WebhookRouter`'s stateless private static methods (`runBeforeHooks`, `runAfterHooks`, `createHandlerEntry`, `parseRequestBody`, `validatePayload`, `executeHandler`) are now module-level functions in `router.ts`. Internal-only change; the public API (`WebhookRouter`, `createWebhookRouter`, `.register()`, `.handle()`) is unaffected.
+
+HMAC signature verification decodes the incoming header's hex signature to bytes and compares it against the computed digest byte-for-byte, instead of hex-encoding the digest and comparing hex text. Behavior is unchanged for valid requests; this only affects internals (fewer bytes compared, and the header's hex is no longer case-normalized as text since decoding handles case natively).
+
+`constantTimeEquals` moved from `utils.ts` into `verify.ts` (its only consumer) and now compares `Uint8Array`s (bytes) instead of strings. Still exported from `@zap-studio/webhooks` and `@zap-studio/webhooks/verify`.
+
+### Removed
+
+Removed the `./utils` subpath export.
+
+## [0.4.0]
+
+### Changed
 
 The custom `NormalizedRequest`/`NormalizedResponse` contract is gone. `router.handle` now takes a standard Web API `Request` and returns a standard `Response`, so the router plugs directly into fetch-native runtimes (Bun, Deno, Cloudflare Workers, Next.js route handlers, Hono) with no adapter layer.
 
-Breaking changes:
+**Breaking changes:**
 
 - `handle(req: NormalizedRequest): Promise<NormalizedResponse>` → `handle(request: Request): Promise<Response>`.
 - Handlers receive `{ request, rawBody, path, payload }` (a `WebhookContext` plus the validated `payload`) and return a `Response` or `undefined` (default `200` `"ok"`). The `ack` helper is removed — use `Response.json(body, init)`.
@@ -14,73 +40,68 @@ Breaking changes:
 
 Behavior kept: hook execution order, prefix semantics (default `/webhooks/`), exact-match routing, HMAC verification, and the `404`/`400`/`500` error body shapes. Unknown routes now return `404` without reading the request body.
 
-## @zap-studio/webhooks@0.3.0
+## [0.3.0]
 
-### Migrate to ultracite lint/format; make the adapter contract generic
+### Changed
 
 `Adapter` and `BaseAdapter` are now generic over the framework request/response types (`Adapter<TReq, TRes>`, `BaseAdapter<TReq, TRes>`), replacing the previous per-method generics. The mapping members (`toNormalizedRequest`, `toFrameworkResponse`, `handleWebhook`) are now arrow properties, so custom adapters must override them with property syntax rather than method syntax.
 
-Also: `register()` now returns `this`, error hooks always receive a real `Error` instance, and `rawBody` is typed as `Uint8Array`.
-
-# @zap-studio/webhooks
+Also: `register()` now returns `this`, error hooks always receive a real `Error` instance, and `rawBody` is typed as `Uint8Array`. Internal formatting and lint cleanup migrated to ultracite.
 
-## 0.2.2
+## [0.2.2]
 
-### Dependencies
+### Changed
 
 - Updated dependency `@zap-studio/validation` to `0.3.4`.
 
-## 0.2.1
-
-### Fixed
-
-- 3a950dc: Preserve registered hook assignment types while keeping the schema-first router API unchanged.
+## [0.2.1]
 
 ### Changed
 
 - 5fa58b1: Reduced webhook router complexity by consolidating hook normalization and handler entry creation.
 - 7004e9f: Allow explicit `undefined` in option handling, then follow with d707800 to remove redundant `| undefined` unions from public types.
 - 9f31f87: Switched the package build to ESNext-aligned output and updated package tooling and publish metadata.
+- Updated dependency `@zap-studio/validation` to `0.3.3`.
 
-### Dependencies
+### Fixed
 
-- Updated dependency `@zap-studio/validation` to `0.3.3`.
+- 3a950dc: Preserve registered hook assignment types while keeping the schema-first router API unchanged.
 
-## 0.2.0
+## [0.2.0]
 
-### Minor Changes
+### Changed
 
 - c686862: Switch `createHmacVerifier` to Web Crypto and standardize the verifier around string secrets.
 
   This change removes the Node `crypto` dependency from the verifier path, keeps `req.rawBody` as `Uint8Array`, simplifies `createHmacVerifier` to take a string secret, and adds public `VerificationError` in `@zap-studio/webhooks/errors` for verifier setup and signature failures.
 
-## 0.1.4
+## [0.1.4]
 
-### Patch Changes
+### Changed
 
 - e26293e: Updated dependencies.
   - @zap-studio/validation@0.3.2
 
-## 0.1.3
+## [0.1.3]
 
-### Patch Changes
+### Changed
 
 - 5ea3d3b: Updated dependencies.
   - @zap-studio/validation@0.3.1
 
-## 0.1.2
+## [0.1.2]
 
-### Patch Changes
+### Fixed
 
 - c209a27: Fix payload schema validation internals to use the current async `standardValidate` options API (`{ throwOnError: false }`), restoring typecheck compatibility after the validation helper signature update.
 
-## 0.1.1
+## [0.1.1]
 
-### Dependencies
+### Changed
 
 - f75b984: Updated dependency `@zap-studio/validation` to `0.3.0`.
 
-## 0.1.0
+## [0.1.0]
 
 ### Added
 

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 alexandretrotel
+Copyright (c) 2026 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

package/README.md

@@ -2,66 +2,53 @@
 
 Schema-first, type-safe webhook routing built on the standard Web API [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) and [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) primitives, with runtime-agnostic signature verification support.
 
-Works with any validation library that implements [Standard Schema](https://github.com/standard-schema/standard-schema), including Zod, Valibot, and ArkType.
+Full documentation: [zapstudio.dev/webhooks](https://www.zapstudio.dev/webhooks)
 
-## 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
+## Installation
 
 ```bash
 npm install @zap-studio/webhooks
 ```
 
-## Quickstart
+You also need a schema library that implements [Standard Schema](https://github.com/standard-schema/standard-schema), such as Zod, Valibot, or ArkType.
+
+## Features
+
+- **Web API native** — `handle(request: Request)` returns a `Response`, so the router plugs directly into Bun, Deno, Cloudflare Workers, Next.js route handlers, Hono, and any other fetch-compatible runtime.
+- **Type-safe routing** — handler payload types are inferred from the route schema.
+- **Standard Schema validation** — bring Zod, Valibot, ArkType, or any compatible library.
+- **Signature verification** — built-in HMAC verifier with constant-time comparison, or plug in your own `verify` function.
+- **Lifecycle hooks** — global `before`, `after`, and `onError` hooks for cross-cutting behavior.
+- **Runtime-agnostic** — uses the Web Crypto API, not Node-specific APIs.
+- **Optional logging** through `createWebhookRouter({ logger })` ([`@zap-studio/logger`](https://www.npmjs.com/package/@zap-studio/logger)) — omit it and there's zero logging overhead.
+- **Tree-shakeable** — validation and hook-running internals are standalone functions; unused exports are dropped by any modern bundler.
+
+## Quick Start
 
 ```ts
+import { ConsoleLogger } from "@zap-studio/logger";
 import { createWebhookRouter } from "@zap-studio/webhooks";
 import { z } from "zod";
 
-const router = createWebhookRouter({
-  prefix: "/webhooks", // default
-});
+const logger = new ConsoleLogger({ minLevel: "debug" });
+const router = createWebhookRouter({ prefix: "/webhooks", logger });
 
 router.register("/payments/succeeded", {
-  schema: z.object({
-    id: z.string(),
-    amount: z.number().positive(),
-    currency: z.string().length(3),
-  }),
+  schema: z.object({ id: z.string(), amount: z.number().positive() }),
   handler: ({ payload }) => {
     // payload is inferred from schema
-    return Response.json(`processed ${payload.id}`);
+    return Response.json({ processed: payload.id });
   },
 });
 
-// Any fetch-compatible runtime: Bun, Deno, Cloudflare Workers, ...
 export default {
   fetch: (request: Request) => router.handle(request),
 };
 ```
 
-`router.handle` takes a standard `Request` and returns a standard `Response`, so the router plugs directly into any fetch-native runtime — no adapter layer needed.
-
-Handlers can return a `Response`, or `undefined` to let the router reply with its default `200` acknowledgement.
-
-### Paths and the prefix
-
-Routes are registered with a leading slash (`"/payments/succeeded"`) and matched relative to the router's `prefix` (default `"/webhooks"`, no trailing slash) — so the example above answers on `/webhooks/payments/succeeded`. Paths are normalized internally: missing leading slashes are added, trailing slashes stripped, and duplicate slashes collapsed, on both registered routes and incoming request URLs. Set `prefix: ""` (or `"/"`) to mount routes at the root.
-
-## Runtime integration
+## Web API Native
 
-Because `handle(request)` speaks fetch, integration is one line in most environments:
+`handle(request: Request)` returns a `Response`, so the router plugs directly into any fetch-compatible runtime.
 
 ```ts
 // Bun / Deno / Cloudflare Workers
@@ -74,150 +61,95 @@ export const POST = (request: Request) => router.handle(request);
 app.all("/webhooks/*", (c) => router.handle(c.req.raw));
 ```
 
-For raw Node `http` servers, use a fetch-to-Node bridge such as [`srvx`](https://srvx.h3.dev) or [`@hono/node-server`](https://github.com/honojs/node-server).
+## Type-Safe Routing
 
-## The webhook context
-
-Hooks, verifiers, and handlers all receive a context object instead of the raw request stream. The router reads the request body exactly once, so the exact bytes stay available for signature verification:
+Handler payload types are inferred from the route schema.
 
 ```ts
-interface WebhookContext {
-  request: Request; // headers, method, url — body already consumed
-  rawBody: Uint8Array; // exact request body bytes
-  path: string; // matched route key, e.g. "/payments/succeeded"
-}
+router.register("/payments/succeeded", {
+  schema: z.object({ id: z.string(), amount: z.number() }),
+  handler: ({ payload }) => {
+    // payload.id: string, payload.amount: number — inferred from schema
+    return Response.json({ ok: true });
+  },
+});
 ```
 
-Handlers additionally receive `payload`, the schema-validated body.
+## Standard Schema Validation
 
-## GitHub webhook example
+Bring Zod, Valibot, ArkType, or any compatible library.
 
 ```ts
-import { createHmacVerifier, createWebhookRouter } from "@zap-studio/webhooks";
 import { z } from "zod";
+// or: import * as v from "valibot"; import { type } from "arktype";
 
-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: ({ payload }) => {
-    console.log(`[github] ${payload.repository.full_name} ${payload.ref}`);
-    return undefined; // default 200 "ok"
-  },
+router.register("/event", {
+  schema: z.object({ id: z.string() }),
+  handler: ({ payload }) => Response.json(payload),
 });
 ```
 
-## Stripe webhook example
+## Signature Verification
 
-```ts
-import Stripe from "stripe";
-import { createWebhookRouter } from "@zap-studio/webhooks";
-import { z } from "zod";
+Built-in HMAC verifier with constant-time comparison, or plug in your own `verify` function.
 
-const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
+```ts
+import {
+  createHmacVerifier,
+  createWebhookRouter,
+  VerificationError,
+} from "@zap-studio/webhooks";
 
 const router = createWebhookRouter({
-  verify: ({ request, rawBody }) => {
-    const signature = request.headers.get("stripe-signature");
-    if (!signature) {
-      throw new Error("Missing Stripe signature");
-    }
-
-    stripe.webhooks.constructEvent(
-      Buffer.from(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"),
+  verify: createHmacVerifier({
+    headerName: "x-hub-signature-256",
+    secret: process.env.WEBHOOK_SECRET!,
   }),
-  handler: ({ payload }) => {
-    console.log(`[stripe] event ${payload.id} (${payload.type})`);
-    return Response.json("received");
+  onError: (error) => {
+    if (error instanceof VerificationError) {
+      return Response.json({ error: "invalid signature" }, { status: 401 });
+    }
   },
 });
 ```
 
-## Lifecycle hooks
+## 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
+Global `before`, `after`, and `onError` hooks for cross-cutting behavior.
 
 ```ts
 const router = createWebhookRouter({
-  before: (ctx) => {
-    console.log("incoming", ctx.path);
-  },
-  after: (_ctx, response) => {
-    console.log("status", response.status);
-  },
+  before: (ctx) => console.log("incoming", ctx.path),
+  after: (_ctx, response) => console.log("status", response.status),
   onError: (error) => Response.json({ error: error.message }, { status: 500 }),
 });
 ```
 
-After-hooks receive the outgoing `Response` as-is. If a hook needs to read the body, call `response.clone()` first so the stream sent to the client stays readable:
+## Runtime-Agnostic
+
+Uses the Web Crypto API, not Node-specific APIs.
 
 ```ts
-const router = createWebhookRouter({
-  after: async (_ctx, response) => {
-    const body = await response.clone().json();
-    console.log("responded with", body);
-  },
+// Uses globalThis.crypto.subtle — no Node `crypto` import required
+const verify = createHmacVerifier({
+  headerName: "x-hub-signature-256",
+  secret: process.env.WEBHOOK_SECRET!,
 });
 ```
 
-## Verification helper
-
-`@zap-studio/webhooks` exports `createHmacVerifier`, a small helper that builds a `verify` function for HMAC-signed webhook providers.
+## Logging
 
-It does not depend on Node APIs. The verifier uses the Web Crypto API, so it works in any runtime that provides `globalThis.crypto.subtle`.
-
-- reads a signature from the header you choose
-- computes an HMAC from `ctx.rawBody`
-- compares signatures in constant time
-- uses the Web Crypto API instead of Node `crypto`
-- works across runtimes that provide `globalThis.crypto.subtle`
-- expects a string secret
-- throws `VerificationError` on verifier setup or signature failures
+Pass a `logger?: Logger` from [`@zap-studio/logger`](https://www.npmjs.com/package/@zap-studio/logger) to `createWebhookRouter(...)` to observe delivery attempts, dispatch, verification failures, and unmatched routes. Omit it and nothing is logged.
 
 ```ts
-import { createHmacVerifier, VerificationError } from "@zap-studio/webhooks";
-
-const verify = createHmacVerifier({
-  headerName: "x-hub-signature-256",
-  secret: process.env.WEBHOOK_SECRET!,
-  algo: "sha256", // optional, defaults to sha256
-});
+import { ConsoleLogger } from "@zap-studio/logger";
+import { createWebhookRouter } from "@zap-studio/webhooks";
 
-try {
-  await verify(ctx);
-} catch (error) {
-  if (error instanceof VerificationError) {
-    console.error("webhook verification failed", error.message);
-  }
-}
+const logger = new ConsoleLogger({ minLevel: "debug" });
+const router = createWebhookRouter({ prefix: "/webhooks", logger });
 ```
 
-Use this when your provider uses standard HMAC signatures. For providers with custom signing formats, pass your own `verify` function.
+Each delivery attempt and handler dispatch logs at `debug`; verification failures and unmatched routes log at `warn`.
 
 ## Runtime Support
 

package/dist/errors.d.ts

@@ -9,6 +9,22 @@
  *
  * This error is used by verifier helpers such as `createHmacVerifier` so
  * callers can distinguish verification failures from other webhook errors.
+ *
+ * @example
+ * ```ts
+ * import { VerificationError } from "@zap-studio/webhooks";
+ *
+ * const response = await router.handle(request);
+ * // Verification failures surface as a 500 response by default, or via onError:
+ * const routerWithHandler = createWebhookRouter({
+ *   verify: createHmacVerifier({ headerName: "x-signature", secret }),
+ *   onError: (error) => {
+ *     if (error instanceof VerificationError) {
+ *       return Response.json({ error: error.message }, { status: 401 });
+ *     }
+ *   },
+ * });
+ * ```
  */
 declare class VerificationError extends Error {
   /**

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","names":[],"sources":["../src/errors.ts"],"mappings":";;;;;;;;;;;;cAYa,0BAA0B;;;;;;EAMrC,YAAY"}
+{"version":3,"file":"errors.d.ts","names":[],"sources":["../src/errors.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;cA4Ba,0BAA0B;;;;;;EAMrC,YAAY"}

package/dist/errors.js

@@ -9,6 +9,22 @@
 *
 * This error is used by verifier helpers such as `createHmacVerifier` so
 * callers can distinguish verification failures from other webhook errors.
+*
+* @example
+* ```ts
+* import { VerificationError } from "@zap-studio/webhooks";
+*
+* const response = await router.handle(request);
+* // Verification failures surface as a 500 response by default, or via onError:
+* const routerWithHandler = createWebhookRouter({
+*   verify: createHmacVerifier({ headerName: "x-signature", secret }),
+*   onError: (error) => {
+*     if (error instanceof VerificationError) {
+*       return Response.json({ error: error.message }, { status: 401 });
+*     }
+*   },
+* });
+* ```
 */
 var VerificationError = class extends Error {
 	/**

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/**\n * Error primitives for webhook verification failures.\n *\n * @module @zap-studio/webhooks/errors\n */\n\n/**\n * Error thrown when webhook request verification fails.\n *\n * This error is used by verifier helpers such as `createHmacVerifier` so\n * callers can distinguish verification failures from other webhook errors.\n */\nexport class VerificationError extends Error {\n  /**\n   * Creates a verification error with a human-readable message.\n   *\n   * @param message - Error message describing the verification failure.\n   */\n  constructor(message: string) {\n    super(message);\n    this.name = \"VerificationError\";\n  }\n}\n"],"mappings":";;;;;;;;;;;;AAYA,IAAa,oBAAb,cAAuC,MAAM;;;;;;CAM3C,YAAY,SAAiB;EAC3B,MAAM,OAAO;EACb,KAAK,OAAO;CACd;AACF"}
+{"version":3,"file":"errors.js","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/**\n * Error primitives for webhook verification failures.\n *\n * @module @zap-studio/webhooks/errors\n */\n\n/**\n * Error thrown when webhook request verification fails.\n *\n * This error is used by verifier helpers such as `createHmacVerifier` so\n * callers can distinguish verification failures from other webhook errors.\n *\n * @example\n * ```ts\n * import { VerificationError } from \"@zap-studio/webhooks\";\n *\n * const response = await router.handle(request);\n * // Verification failures surface as a 500 response by default, or via onError:\n * const routerWithHandler = createWebhookRouter({\n *   verify: createHmacVerifier({ headerName: \"x-signature\", secret }),\n *   onError: (error) => {\n *     if (error instanceof VerificationError) {\n *       return Response.json({ error: error.message }, { status: 401 });\n *     }\n *   },\n * });\n * ```\n */\nexport class VerificationError extends Error {\n  /**\n   * Creates a verification error with a human-readable message.\n   *\n   * @param message - Error message describing the verification failure.\n   */\n  constructor(message: string) {\n    super(message);\n    this.name = \"VerificationError\";\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,IAAa,oBAAb,cAAuC,MAAM;;;;;;CAM3C,YAAY,SAAiB;EAC3B,MAAM,OAAO;EACb,KAAK,OAAO;CACd;AACF"}

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 import { VerificationError } from "./errors.js";
-import { AfterHook, BeforeHook, ErrorHook, HandlerContext, HandlerMap, InferSchemaOutput, InferWebhookMapFromRoutes, RegisterOptions, SchemaRouteOptions, SchemaRoutes, VerifyFn, WebhookContext, WebhookHandler } from "./types.js";
-import { WebhookRouter, WebhookRouterOptions, createWebhookRouter } from "./router.js";
-import { constantTimeEquals } from "./utils.js";
-import { createHmacVerifier } from "./verify.js";
+import { AfterHook, BeforeHook, ErrorHook, HandlerContext, HandlerMap, InferSchemaOutput, InferWebhookMapFromRoutes, RegisterOptions, SchemaRouteOptions, SchemaRoutes, VerifyFn, WebhookContext, WebhookHandler, WebhookRouterOptions } from "./types.js";
+import { WebhookRouter, createWebhookRouter } from "./router.js";
+import { constantTimeEquals, createHmacVerifier } from "./verify.js";
 export { type AfterHook, type BeforeHook, type ErrorHook, type HandlerContext, type HandlerMap, type InferSchemaOutput, type InferWebhookMapFromRoutes, type RegisterOptions, type SchemaRouteOptions, type SchemaRoutes, VerificationError, type VerifyFn, type WebhookContext, type WebhookHandler, WebhookRouter, type WebhookRouterOptions, constantTimeEquals, createHmacVerifier, createWebhookRouter };

package/dist/index.js

@@ -1,5 +1,4 @@
 import { VerificationError } from "./errors.js";
 import { WebhookRouter, createWebhookRouter } from "./router.js";
-import { constantTimeEquals } from "./utils.js";
-import { createHmacVerifier } from "./verify.js";
+import { constantTimeEquals, createHmacVerifier } from "./verify.js";
 export { VerificationError, WebhookRouter, constantTimeEquals, createHmacVerifier, createWebhookRouter };