hono-webhooks 0.5.1 → 0.6.0

package/dist/cli.js

@@ -5657,8 +5657,10 @@ function superRefine(fn, params) {
 }
 // src/index.ts
 import { Hono } from "hono";
+import { bodyLimit } from "hono/body-limit";
 import { HTTPException } from "hono/http-exception";
 import { basePath } from "hono/route";
+var DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
 
 class WebhookValidationError extends HTTPException {
   target;
@@ -5709,7 +5711,7 @@ async function parse3(schema, value, target) {
 }
 function defaultErrorResponse(error, c, log) {
   if (error instanceof WebhookValidationError) {
-    return c.json({ error: error.message, issues: error.issues }, error.status);
+    return error.target === "signature" ? c.json({ error: error.message }, error.status) : c.json({ error: error.message, issues: error.issues }, error.status);
   }
   if (error instanceof HTTPException) {
     return error.res ?? c.json({ error: error.message }, error.status);
@@ -5734,6 +5736,9 @@ function makeCreateWebhooks() {
     const app = new Hono;
     const methodsByPath = new Map;
     for (const { config } of webhooks) {
+      if (config.method !== "GET" && config.verify === undefined) {
+        throw new Error(`hono-webhooks: ${config.method} ${config.path} has no verify. Pass a verify function, or verify: false if it is public on purpose.`);
+      }
       const methods = methodsByPath.get(config.path) ?? [];
       if (methods.includes(config.method)) {
         throw new Error(`hono-webhooks: ${config.method} ${config.path} is defined twice`);
@@ -5775,15 +5780,32 @@ function makeCreateWebhooks() {
     const ordered = [...webhooks].sort((a, b) => Number(isDynamic(a.config.path)) - Number(isDynamic(b.config.path)));
     for (const { config, handler } of ordered) {
       app.on(config.method, config.path, handle(config.path, async (c, event) => {
+        const maxSize = config.maxBodyBytes ?? options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+        if (maxSize !== Infinity) {
+          await bodyLimit({
+            maxSize,
+            onError: () => {
+              throw new HTTPException(413, { message: "Payload too large" });
+            }
+          })(c, async () => {});
+        }
         event.rawBody = await c.req.text();
-        if (config.verify && !await config.verify({
-          c,
-          rawBody: event.rawBody,
-          headers: c.req.header()
-        })) {
-          throw new WebhookValidationError("signature", [
-            { message: "Signature does not match" }
-          ]);
+        if (config.verify) {
+          let reason = "Signature does not match";
+          const ok = await config.verify({
+            c,
+            rawBody: event.rawBody,
+            headers: c.req.header(),
+            fail: (why) => {
+              reason = why;
+              return false;
+            }
+          });
+          if (ok !== true) {
+            throw new WebhookValidationError("signature", [
+              { message: reason }
+            ]);
+          }
         }
         event.params = await parse3(config.params, c.req.param(), "params");
         event.query = await parse3(config.query, c.req.query(), "query");
@@ -5860,6 +5882,7 @@ function describeWebhooks(source, { target = "draft-2020-12" } = {}) {
 
 // src/signatures.ts
 var encoder = new TextEncoder;
+var reject = (input, reason) => input.fail?.(reason) ?? false;
 function hmacKey(secret, hash) {
   if (!secret.length) {
     throw new Error("hono-webhooks: the signing secret is empty");
@@ -5889,19 +5912,23 @@ function fromBase64(base64) {
   }
 }
 var resolveSecret = async (secret, c) => typeof secret === "function" ? secret(c) : secret;
+var signedUrls = async (url, c) => [await url?.(c) ?? c.req.url].flat();
+var outsideTolerance = (seconds, toleranceSeconds) => Math.abs(Date.now() / 1000 - seconds) > toleranceSeconds;
 function hmac(options) {
   const { header, encoding, prefix = "", hash = "SHA-256" } = options;
   const name = header.toLowerCase();
   return {
-    verify: (secret) => async ({ c, rawBody, headers }) => {
-      const value = headers[name];
-      if (!value?.startsWith(prefix))
-        return false;
+    verify: (secret) => async (input) => {
+      const value = input.headers[name];
+      if (!value)
+        return reject(input, "missing-header");
+      if (!value.startsWith(prefix))
+        return reject(input, "malformed");
       const encoded = value.slice(prefix.length);
       const signature = encoding === "hex" ? fromHex(encoded) : fromBase64(encoded);
       if (!signature)
-        return false;
-      return hmacVerify(await resolveSecret(secret, c), rawBody, signature, hash);
+        return reject(input, "malformed");
+      return await hmacVerify(await resolveSecret(secret, input.c), input.rawBody, signature, hash) || reject(input, "mismatch");
     },
     async sign(rawBody, secret) {
       const signature = await hmacSign(secret, rawBody, hash);
@@ -5916,27 +5943,31 @@ var github = hmac({
   encoding: "hex",
   prefix: "sha256="
 });
+var meta2 = github;
 var shopify = hmac({
   header: "x-shopify-hmac-sha256",
   encoding: "base64"
 });
 var stripe = {
-  verify: (secret, { toleranceSeconds = 300 } = {}) => async ({ c, rawBody, headers }) => {
-    const parts = (headers["stripe-signature"] ?? "").split(",").map((part) => part.split("="));
+  verify: (secret, { toleranceSeconds = 300 } = {}) => async (input) => {
+    const header = input.headers["stripe-signature"];
+    if (!header)
+      return reject(input, "missing-header");
+    const parts = header.split(",").map((part) => part.split("="));
     const timestamp = parts.find(([k]) => k === "t")?.[1] ?? "";
     if (!/^\d+$/.test(timestamp))
-      return false;
-    if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) {
-      return false;
+      return reject(input, "malformed");
+    if (outsideTolerance(Number(timestamp), toleranceSeconds)) {
+      return reject(input, "timestamp-out-of-tolerance");
     }
-    const key = await resolveSecret(secret, c);
+    const key = await resolveSecret(secret, input.c);
     for (const [k, v] of parts) {
       const signature = k === "v1" && v ? fromHex(v) : undefined;
-      if (signature && await hmacVerify(key, `${timestamp}.${rawBody}`, signature)) {
+      if (signature && await hmacVerify(key, `${timestamp}.${input.rawBody}`, signature)) {
         return true;
       }
     }
-    return false;
+    return reject(input, "mismatch");
   },
   async sign(rawBody, secret, { timestamp } = {}) {
     const t = timestamp ?? Math.floor(Date.now() / 1000);
@@ -5952,25 +5983,29 @@ function svixKey(secret) {
   return key;
 }
 var svix = {
-  verify: (secret, { toleranceSeconds = 300 } = {}) => async ({ c, rawBody, headers }) => {
+  verify: (secret, { toleranceSeconds = 300 } = {}) => async (input) => {
+    const { headers } = input;
     const prefix = headers["svix-id"] ? "svix" : "webhook";
     const id = headers[`${prefix}-id`];
-    const timestamp = headers[`${prefix}-timestamp`] ?? "";
+    const timestamp = headers[`${prefix}-timestamp`];
     const signatures = headers[`${prefix}-signature`];
-    if (!id || !signatures || !/^\d+$/.test(timestamp))
-      return false;
-    if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) {
-      return false;
+    if (!id || !signatures || !timestamp) {
+      return reject(input, "missing-header");
+    }
+    if (!/^\d+$/.test(timestamp))
+      return reject(input, "malformed");
+    if (outsideTolerance(Number(timestamp), toleranceSeconds)) {
+      return reject(input, "timestamp-out-of-tolerance");
     }
-    const key = svixKey(await resolveSecret(secret, c));
+    const key = svixKey(await resolveSecret(secret, input.c));
     for (const entry of signatures.split(" ")) {
       const [version, encoded] = entry.split(",");
       const signature = version === "v1" && encoded ? fromBase64(encoded) : undefined;
-      if (signature && await hmacVerify(key, `${id}.${timestamp}.${rawBody}`, signature)) {
+      if (signature && await hmacVerify(key, `${id}.${timestamp}.${input.rawBody}`, signature)) {
         return true;
       }
     }
-    return false;
+    return reject(input, "mismatch");
   },
   async sign(rawBody, secret, { id, timestamp } = {}) {
     const msgId = id ?? `msg_${crypto.randomUUID().replaceAll("-", "")}`;
@@ -5983,14 +6018,122 @@ var svix = {
     };
   }
 };
+var infisical = {
+  verify: (secret, { toleranceSeconds = 300 } = {}) => async (input) => {
+    const header = input.headers["x-infisical-signature"];
+    if (!header)
+      return reject(input, "missing-header");
+    const signature = fromHex(header.split(";")[1] ?? "");
+    if (!signature?.length)
+      return reject(input, "malformed");
+    let timestamp;
+    try {
+      timestamp = JSON.parse(input.rawBody)?.timestamp;
+    } catch {}
+    if (typeof timestamp !== "number")
+      return reject(input, "malformed");
+    if (!await hmacVerify(await resolveSecret(secret, input.c), input.rawBody, signature)) {
+      return reject(input, "mismatch");
+    }
+    return !outsideTolerance(timestamp / 1000, toleranceSeconds) || reject(input, "timestamp-out-of-tolerance");
+  },
+  async sign(rawBody, secret) {
+    let t;
+    try {
+      t = JSON.parse(rawBody)?.timestamp;
+    } catch {}
+    const signature = toHex(await hmacSign(secret, rawBody));
+    return { "x-infisical-signature": `t=${t ?? Date.now()};${signature}` };
+  }
+};
+function twilioPayload(url, rawBody) {
+  const fields = [...new URLSearchParams(rawBody)].sort(([a, x], [b, y]) => a === b ? x < y ? -1 : 1 : a < b ? -1 : 1);
+  return url + fields.map(([k, v]) => k + v).join("");
+}
+var twilio = {
+  verify: (secret, { url } = {}) => async (input) => {
+    const signature = input.headers["x-twilio-signature"];
+    if (!signature)
+      return reject(input, "missing-header");
+    const bytes = fromBase64(signature);
+    if (!bytes)
+      return reject(input, "malformed");
+    const key = await resolveSecret(secret, input.c);
+    for (const candidate of await signedUrls(url, input.c)) {
+      const payload = twilioPayload(candidate, input.rawBody);
+      if (await hmacVerify(key, payload, bytes, "SHA-1"))
+        return true;
+    }
+    return reject(input, "mismatch");
+  },
+  async sign(rawBody, secret, options) {
+    if (!options?.url)
+      throw new Error("hono-webhooks: twilio.sign needs a url");
+    const signature = await hmacSign(secret, twilioPayload(options.url, rawBody), "SHA-1");
+    return { "x-twilio-signature": toBase64(signature) };
+  }
+};
+var HUBSPOT_DECODE = {
+  "%3A": ":",
+  "%2F": "/",
+  "%3F": "?",
+  "%40": "@",
+  "%21": "!",
+  "%24": "$",
+  "%27": "'",
+  "%28": "(",
+  "%29": ")",
+  "%2A": "*",
+  "%2C": ",",
+  "%3B": ";"
+};
+var hubspotUrl = (url) => url.replace(/%(3A|2F|3F|40|21|24|27|28|29|2A|2C|3B)/gi, (match) => HUBSPOT_DECODE[match.toUpperCase()] ?? match);
+var hubspot = {
+  verify: (secret, { url, toleranceSeconds = 300 } = {}) => async (input) => {
+    const signature = input.headers["x-hubspot-signature-v3"];
+    const timestamp = input.headers["x-hubspot-request-timestamp"];
+    if (!signature || !timestamp)
+      return reject(input, "missing-header");
+    const bytes = fromBase64(signature);
+    if (!bytes || !/^\d+$/.test(timestamp))
+      return reject(input, "malformed");
+    if (outsideTolerance(Number(timestamp) / 1000, toleranceSeconds)) {
+      return reject(input, "timestamp-out-of-tolerance");
+    }
+    const key = await resolveSecret(secret, input.c);
+    const method = input.c.req.method.toUpperCase();
+    for (const candidate of await signedUrls(url, input.c)) {
+      const payload = `${method}${hubspotUrl(candidate)}${input.rawBody}${timestamp}`;
+      if (await hmacVerify(key, payload, bytes))
+        return true;
+    }
+    return reject(input, "mismatch");
+  },
+  async sign(rawBody, secret, options) {
+    if (!options?.url)
+      throw new Error("hono-webhooks: hubspot.sign needs a url");
+    const t = options.timestamp ?? Date.now();
+    const method = (options.method ?? "POST").toUpperCase();
+    const signature = await hmacSign(secret, `${method}${hubspotUrl(options.url)}${rawBody}${t}`);
+    return {
+      "x-hubspot-signature-v3": toBase64(signature),
+      "x-hubspot-request-timestamp": String(t)
+    };
+  }
+};
 
 // src/cli-commands.ts
 var schemes = {
   github,
+  hubspot,
+  infisical,
+  meta: meta2,
   shopify,
   stripe,
-  svix
+  svix,
+  twilio
 };
+var ORIGIN = "http://localhost";
 var importModule = (specifier) => existsSync(resolve(specifier)) ? import(pathToFileURL(resolve(specifier)).href) : import(specifier);
 function isWebhooksApp(value) {
   return typeof value === "object" && value !== null && Array.isArray(value.webhooks) && typeof value.request === "function";
@@ -6042,6 +6185,8 @@ var list = defineCommand2({
       print(ctx, `${config.method.padEnd(7)} ${config.path}${config.description ? `  ${config.description}` : ""}`);
       if (validates)
         print(ctx, `        validates ${validates}`);
+      if (config.verify === false)
+        print(ctx, "        public (verify: false)");
     }
   }
 });
@@ -6126,6 +6271,7 @@ var testCommand = defineCommand2({
         headers.set("content-type", "text/plain");
       }
     }
+    const url = `${path.startsWith("/") ? path : `/${path}`}${input.query ? `?${input.query}` : ""}`;
     if (input.sign) {
       const scheme = schemes[input.sign];
       if (!scheme) {
@@ -6137,11 +6283,13 @@ var testCommand = defineCommand2({
       const secret = ctx.env[name];
       if (secret === undefined)
         throw new CliError2(`${name} is not set`);
-      for (const [key, value] of Object.entries(await scheme.sign(input.body ?? "", secret))) {
+      for (const [key, value] of Object.entries(await scheme.sign(input.body ?? "", secret, {
+        url: ORIGIN + url,
+        method: method.toUpperCase()
+      }))) {
         headers.set(key, value);
       }
     }
-    const url = `${path.startsWith("/") ? path : `/${path}`}${input.query ? `?${input.query}` : ""}`;
     const start = performance.now();
     const res = await ctx.context.request(url, {
       method: method.toUpperCase(),

package/dist/index.d.ts

@@ -35,8 +35,17 @@ export interface VerifyInput<E extends Env = any> {
     rawBody: string;
     /** All request headers, lower-case names, not schema-validated. */
     headers: Record<string, string>;
+    /**
+     * Records why the check failed and returns `false`:
+     * `return fail('timestamp-out-of-tolerance')`. The reason reaches
+     * `onEvent` (`validation.issues[0].message`), never the response.
+     */
+    fail(reason: string): false;
 }
-/** Checks a request's signature. `hono-webhooks/signatures` has ready-made ones. */
+/**
+ * Checks a request's signature. `hono-webhooks/signatures` has ready-made
+ * ones. Only `true` lets the request through.
+ */
 export type Verify<E extends Env = any> = (input: VerifyInput<E>) => MaybePromise<boolean>;
 export interface WebhookConfig<P extends string = string, TParams extends Schema | undefined = Schema | undefined, TQuery extends Schema | undefined = Schema | undefined, THeaders extends Schema | undefined = Schema | undefined, TBody extends Schema | undefined = Schema | undefined, TResponse extends Schema | undefined = Schema | undefined, E extends Env = any> {
     method: WebhookMethod;
@@ -51,9 +60,14 @@ export interface WebhookConfig<P extends string = string, TParams extends Schema
      * Checks the signature right after routing, before anything is validated
      * or parsed. Returning `false` answers `401 { error: 'Invalid signature' }`.
      *
+     * Required for every method but `GET`: pass `false` for a webhook that is
+     * public on purpose, or `createWebhooks` throws.
+     *
      * @example verify: shopify.verify((c) => c.env.SHOPIFY_SECRET)
      */
-    verify?: Verify<E>;
+    verify?: Verify<E> | false;
+    /** Overrides `WebhooksOptions.maxBodyBytes` for this webhook. */
+    maxBodyBytes?: number;
     /**
      * Checks what the handler returns. A mismatch is reported on
      * `WebhookEvent.validation` and the response is still sent.
@@ -152,6 +166,12 @@ export interface WebhooksOptions<E extends Env = any> {
      * @default true
      */
     logErrors?: boolean;
+    /**
+     * Larger bodies answer `413 { error: 'Payload too large' }` before they
+     * are read. `Infinity` turns the limit off. Each webhook can override it.
+     * @default 1_048_576 (1 MiB)
+     */
+    maxBodyBytes?: number;
 }
 export type WebhooksApp<E extends Env = any> = Hono<E> & {
     /** The definitions, in the order they were passed. */
@@ -172,7 +192,12 @@ export declare class WebhookValidationError extends HTTPException {
  *
  * @example
  * defineWebhook(
- *   { method: 'POST', path: '/orders/:id', body: z.object({ total: z.number() }) },
+ *   {
+ *     method: 'POST',
+ *     path: '/orders/:id',
+ *     verify: shopify.verify((c) => c.env.SHOPIFY_SECRET),
+ *     body: z.object({ total: z.number() })
+ *   },
  *   async ({ params, body }) => ({ id: params.id, total: body.total })
  * )
  */
@@ -180,7 +205,8 @@ export declare const defineWebhook: <const P extends string, TParams extends Sch
 /**
  * Builds a Hono app that serves the webhooks. Mount it under a prefix:
  * `app.route('/webhooks', createWebhooks([...]))`. Unknown paths below the
- * prefix answer 404, known paths with the wrong method answer 405.
+ * prefix answer 404, known paths with the wrong method answer 405. Throws
+ * for a duplicate route and for a non-GET webhook without `verify`.
  */
 export declare const createWebhooks: (webhooks: readonly Webhook<any, string, any, any, any, any, any>[], options?: WebhooksOptions<any>) => WebhooksApp<any>;
 /**
@@ -213,6 +239,8 @@ export interface WebhookEventSummary {
     userAgent: string | null;
     params: Record<string, unknown> | null;
     query: Record<string, unknown> | null;
+    /** Only the headers named in `SummaryOptions.headers`; absent without that option. */
+    headers?: Record<string, string>;
     body: unknown;
     response: unknown;
     /** `null` for validation failures, which `validation` describes. */
@@ -231,19 +259,31 @@ export interface WebhookEventSummary {
         }[];
     } | null;
 }
+/** What `summarizeEvent` keeps. Defaults keep everything but headers. */
+export interface SummaryOptions {
+    /** `false` sets `body` and `response` to `null`. @default true */
+    body?: boolean;
+    /** `false` sets `query` to `null`. @default true */
+    query?: boolean;
+    /**
+     * Request headers to keep, lower-case, e.g. a delivery id such as
+     * `x-github-delivery` or `svix-id`. @default []
+     */
+    headers?: readonly string[];
+}
 /**
- * Flattens an event for logging or storage. Request headers are left out on
- * purpose: they carry signatures and credentials.
+ * Flattens an event for logging or storage. Request headers are left out
+ * unless named in `options.headers`: they carry signatures and credentials.
  *
  * @example
- * onEvent: (e) => db.insert(webhookCalls).values(summarizeEvent(e))
+ * onEvent: (e) => db.insert(webhookCalls).values(summarizeEvent(e, { body: false }))
  */
-export declare function summarizeEvent(event: WebhookEvent): WebhookEventSummary;
+export declare function summarizeEvent(event: WebhookEvent, options?: SummaryOptions): WebhookEventSummary;
 export interface WebhookDescription {
     method: WebhookMethod;
     path: string;
     description: string | null;
-    /** Whether the webhook has a `verify` function. */
+    /** Whether the webhook has a `verify` function; `false` for `verify: false`. */
     verified: boolean;
     bodyType: BodyType;
     /**
@@ -275,8 +315,20 @@ export type TestWebhookInput<W> = W extends Webhook<infer E, infer P, infer TPar
      * webhook's `bodyType` is `'form'`.
      */
     body?: In<TBody, unknown> | string;
-    /** Headers computed from the raw body, e.g. `(raw) => shopify.sign(raw, secret)`. */
-    sign?: (rawBody: string) => MaybePromise<Record<string, string>>;
+    /**
+     * Headers computed from the raw body and the request, e.g.
+     * `(raw) => shopify.sign(raw, secret)` or
+     * `(raw, { url }) => twilio.sign(raw, token, { url })`.
+     */
+    sign?: (rawBody: string, request: {
+        url: string;
+        method: string;
+    }) => MaybePromise<Record<string, string>>;
+    /**
+     * Origin the request is sent to, for schemes that sign the URL.
+     * @default 'http://localhost'
+     */
+    baseUrl?: string;
     /** Bindings, available as `c.env`. */
     env?: E extends {
         Bindings: infer B;
@@ -295,3 +347,9 @@ export type TestWebhookInput<W> = W extends Webhook<infer E, infer P, infer TPar
  * })
  */
 export declare function testWebhook<W extends Webhook>(webhook: W, input?: TestWebhookInput<W>): Promise<Response>;
+/**
+ * The webhook's path with `params` filled in, relative to the mount point:
+ * `webhookPath(oauthCallback, { provider: 'gmail' })` gives
+ * `/channels/gmail/callback`. Prepend your origin and mount prefix for a URL.
+ */
+export declare function webhookPath<P extends string>(webhook: Webhook<any, P>, ...[params]: [ParamKeys<P>] extends [never] ? [] : [PathParams<P>]): string;

package/dist/index.js

@@ -1,7 +1,9 @@
 // src/index.ts
 import { Hono } from "hono";
+import { bodyLimit } from "hono/body-limit";
 import { HTTPException } from "hono/http-exception";
 import { basePath } from "hono/route";
+var DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
 
 class WebhookValidationError extends HTTPException {
   target;
@@ -52,7 +54,7 @@ async function parse(schema, value, target) {
 }
 function defaultErrorResponse(error, c, log) {
   if (error instanceof WebhookValidationError) {
-    return c.json({ error: error.message, issues: error.issues }, error.status);
+    return error.target === "signature" ? c.json({ error: error.message }, error.status) : c.json({ error: error.message, issues: error.issues }, error.status);
   }
   if (error instanceof HTTPException) {
     return error.res ?? c.json({ error: error.message }, error.status);
@@ -77,6 +79,9 @@ function makeCreateWebhooks() {
     const app = new Hono;
     const methodsByPath = new Map;
     for (const { config } of webhooks) {
+      if (config.method !== "GET" && config.verify === undefined) {
+        throw new Error(`hono-webhooks: ${config.method} ${config.path} has no verify. Pass a verify function, or verify: false if it is public on purpose.`);
+      }
       const methods = methodsByPath.get(config.path) ?? [];
       if (methods.includes(config.method)) {
         throw new Error(`hono-webhooks: ${config.method} ${config.path} is defined twice`);
@@ -118,15 +123,32 @@ function makeCreateWebhooks() {
     const ordered = [...webhooks].sort((a, b) => Number(isDynamic(a.config.path)) - Number(isDynamic(b.config.path)));
     for (const { config, handler } of ordered) {
       app.on(config.method, config.path, handle(config.path, async (c, event) => {
+        const maxSize = config.maxBodyBytes ?? options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+        if (maxSize !== Infinity) {
+          await bodyLimit({
+            maxSize,
+            onError: () => {
+              throw new HTTPException(413, { message: "Payload too large" });
+            }
+          })(c, async () => {});
+        }
         event.rawBody = await c.req.text();
-        if (config.verify && !await config.verify({
-          c,
-          rawBody: event.rawBody,
-          headers: c.req.header()
-        })) {
-          throw new WebhookValidationError("signature", [
-            { message: "Signature does not match" }
-          ]);
+        if (config.verify) {
+          let reason = "Signature does not match";
+          const ok = await config.verify({
+            c,
+            rawBody: event.rawBody,
+            headers: c.req.header(),
+            fail: (why) => {
+              reason = why;
+              return false;
+            }
+          });
+          if (ok !== true) {
+            throw new WebhookValidationError("signature", [
+              { message: reason }
+            ]);
+          }
         }
         event.params = await parse(config.params, c.req.param(), "params");
         event.query = await parse(config.query, c.req.query(), "query");
@@ -191,8 +213,15 @@ function issuePath(issue) {
   const path = issue.path?.map((segment) => String(typeof segment === "object" ? segment.key : segment)).join(".");
   return path || null;
 }
-function summarizeEvent(event) {
+function summarizeEvent(event, options = {}) {
   const { c, error, validation } = event;
+  const keepBody = options.body ?? true;
+  const headers = {};
+  for (const name of options.headers ?? []) {
+    const value = c.req.header(name);
+    if (value !== undefined)
+      headers[name] = value;
+  }
   return {
     route: event.route ?? null,
     method: event.method,
@@ -202,9 +231,10 @@ function summarizeEvent(event) {
     ip: c.req.header("x-forwarded-for")?.split(",")[0]?.trim() || c.req.header("x-real-ip") || c.req.header("cf-connecting-ip") || null,
     userAgent: c.req.header("user-agent") ?? null,
     params: event.params ?? null,
-    query: event.query ?? null,
-    body: event.body ?? null,
-    response: event.response ?? null,
+    query: options.query === false ? null : event.query ?? null,
+    ...options.headers && { headers },
+    body: keepBody ? event.body ?? null : null,
+    response: keepBody ? event.response ?? null : null,
     error: error === undefined || error instanceof WebhookValidationError ? null : error instanceof Error ? {
       name: error.name,
       message: error.message,
@@ -253,7 +283,13 @@ function fillPath(pattern, params) {
 }
 async function testWebhook(webhook, input = {}) {
   const { config } = webhook;
-  const { body, sign, env, options } = input;
+  const {
+    body,
+    sign,
+    env,
+    options,
+    baseUrl = "http://localhost"
+  } = input;
   const headers = new Headers(input.headers);
   let rawBody;
   if (typeof body === "string") {
@@ -271,12 +307,16 @@ async function testWebhook(webhook, input = {}) {
       headers.set("content-type", "application/json");
     }
   }
-  for (const [name, value] of Object.entries(await sign?.(rawBody ?? "") ?? {})) {
-    headers.set(name, value);
-  }
   const path = input.path ?? fillPath(config.path, input.params ?? {});
   const query = new URLSearchParams(input.query).toString();
-  return createWebhooks([webhook], options).request(`${path || "/"}${query ? `?${query}` : ""}`, { method: config.method, headers, body: rawBody }, env);
+  const url = `${baseUrl.replace(/\/$/, "")}${path || "/"}${query ? `?${query}` : ""}`;
+  for (const [name, value] of Object.entries(await sign?.(rawBody ?? "", { url, method: config.method }) ?? {})) {
+    headers.set(name, value);
+  }
+  return createWebhooks([webhook], options).request(url, { method: config.method, headers, body: rawBody }, env);
+}
+function webhookPath(webhook, ...[params]) {
+  return fillPath(webhook.config.path, params ?? {}) || "/";
 }
 export {
   WebhookValidationError,
@@ -286,5 +326,6 @@ export {
   describeWebhooks,
   formatIssues,
   summarizeEvent,
-  testWebhook
+  testWebhook,
+  webhookPath
 };

package/dist/otel.d.ts

@@ -1,6 +1,6 @@
 import { type Meter, type Span, type Tracer } from '@opentelemetry/api';
 import type { Env } from 'hono';
-import { type WebhookEvent, type WebhookEventSummary, type WebhooksOptions } from 'hono-webhooks';
+import { type SummaryOptions, type WebhookEvent, type WebhookEventSummary, type WebhooksOptions } from 'hono-webhooks';
 /** The `route` label for 404s, which match no webhook. */
 export declare const UNMATCHED_ROUTE = "__unmatched__";
 /** A metric `otelWebhooks` records, described for a metric catalog. */
@@ -39,6 +39,8 @@ export interface WebhookCall extends WebhookEventSummary {
     /** `error` for 5xx, `warn` for 4xx, else `info`. */
     level: 'info' | 'warn' | 'error';
     outcome: 'success' | 'failed' | 'validation_failed';
+    /** The route is in `ignoreRoutes`: no metrics or log were recorded. */
+    ignored: boolean;
 }
 /** `console` fits, as does any logger with these three methods. */
 export type WebhookLogger = Record<WebhookCall['level'], (message: string, fields: Record<string, string | number>) => void>;
@@ -49,16 +51,18 @@ export interface OtelWebhooksOptions<E extends Env = any> {
     meter?: Meter;
     /** Routes that get a span but no metrics, e.g. `['/health']`. */
     ignoreRoutes?: readonly string[];
+    /** What `call` keeps of the request, as for `summarizeEvent`. */
+    summary?: SummaryOptions;
     /**
-     * Called after every request, ignored routes included, with the span
-     * still active: log it, store it. A returned promise is handled like
-     * `onEvent`'s.
+     * Called after every request, ignored routes included (`call.ignored`),
+     * with the span still active: log it, store it. A returned promise is
+     * handled like `onEvent`'s.
      */
     onWebhookCall?: (call: WebhookCall, event: WebhookEvent<E>) => void | Promise<void>;
     /**
      * Logs one `webhook.completed` event per request at `call.level`, with
      * `route`, `method`, `status_code`, `duration_ms`, `status` (the outcome)
-     * and `error_type`. 404s and `ignoreRoutes` are skipped. Called with the
+     * `error_type` and `error_message`. 404s and `ignoreRoutes` are skipped. Called with the
      * request's span, so the logger can attach to it.
      *
      * @example