hono-webhooks 0.1.1 → 0.2.0

package/README.md

@@ -32,16 +32,19 @@ app.route('/webhooks', createWebhooks([orderPaid]))
   value is checked against the `response` schema.
 - **Any schema library.** Zod, Valibot, ArkType, Effect Schema, or anything
   else that implements Standard Schema. Async schemas work too.
-- **Raw body included.** `rawBody` is always passed next to the parsed body,
-  so you can verify signatures (Stripe, GitHub, Shopify, ...) without extra
-  setup.
+- **Signed webhooks built in.** `verify` checks the signature on the raw
+  body before anything is parsed, with ready-made verifiers and signers for
+  Stripe, GitHub, Shopify and any HMAC scheme. `rawBody` is always passed to
+  the handler too.
 - **Plain Hono.** `createWebhooks` returns a Hono app. Handlers get the Hono
   context `c`, Hono middleware works, `HTTPException` works, and it runs on
   every runtime Hono supports.
 - **One hook for observability.** `onEvent` fires once per request with the
   route, status, duration, validated input, response and error. Use it for
   logs, metrics, traces or an audit table.
-- **A CLI** to list webhooks, print their JSON Schemas and send test requests.
+- **Tooling.** `describeWebhooks` gives JSON Schemas for docs and admin pages,
+  `testWebhook` runs one webhook in tests with typed input, and the CLI lists
+  webhooks and sends (signed) test requests.
 
 ## Contents
 
@@ -50,14 +53,17 @@ app.route('/webhooks', createWebhooks([orderPaid]))
 - [Handler input](#handler-input)
 - [Return values](#return-values)
 - [Body parsing](#body-parsing)
+- [Signature verification](#signature-verification)
 - [Mounting](#mounting)
 - [Typed env and middleware](#typed-env-and-middleware)
 - [Errors](#errors)
 - [Observability with `onEvent`](#observability-with-onevent)
 - [Recipes](#recipes)
+- [Describing webhooks](#describing-webhooks)
 - [Testing](#testing)
 - [CLI](#cli)
 - [API reference](#api-reference)
+- [Upgrading from 0.1](#upgrading-from-01)
 - [Migrating from `createHttpRoute`](#migrating-from-createhttproute)
 - [Releasing](#releasing)
 
@@ -69,7 +75,7 @@ bun add hono-webhooks hono
 bun add zod
 ```
 
-`hono` (4.6 or newer) is a peer dependency. The package is ESM only. Bun
+`hono` (4.8 or newer) is a peer dependency. The package is ESM only. Bun
 loads the TypeScript source directly; Node and bundlers load the built files
 from `dist`.
 
@@ -108,6 +114,7 @@ export const updateItem = defineWebhook(
 | `query`       | Standard Schema                                               | Validates the query string as `Record<string, string>`.                                                 |
 | `headers`     | Standard Schema                                               | Validates headers as `Record<string, string>` with **lower-case** names.                                |
 | `body`        | Standard Schema                                               | Validates the parsed body (see [Body parsing](#body-parsing)).                                          |
+| `verify`      | `({ c, rawBody, headers }) => boolean \| Promise<boolean>`     | Checks the signature before the body is parsed (see [Signature verification](#signature-verification)). |
 | `response`    | Standard Schema                                               | Types the handler's return value and checks it at runtime (see [Return values](#return-values)).        |
 | `bodyType`    | `'auto' \| 'json' \| 'form' \| 'text'`                        | How to parse the body. Default `'auto'`.                                                                |
 | `description` | `string`                                                      | Shown by `hono-webhooks list`.                                                                          |
@@ -170,6 +177,60 @@ The body is read once as text (`rawBody`), then parsed according to
 An empty body is `undefined` (the schema decides whether that's allowed).
 Malformed JSON is a `400` with `issues: [{ message: 'Malformed JSON' }]`.
 
+## Signature verification
+
+`verify` runs after the params, query and headers are validated but **before
+the body is parsed**, on the raw body. A request with a bad signature never
+reaches JSON parsing or the body schema, so signed webhooks can use `body`
+like any other webhook:
+
+```ts
+import { shopify } from 'hono-webhooks/signatures'
+
+export const orderCreated = defineWebhook(
+	{
+		method: 'POST',
+		path: '/shopify/orders',
+		verify: shopify.verify((c) => c.env.SHOPIFY_WEBHOOK_SECRET),
+		body: z.object({ id: z.number(), total_price: z.string() })
+	},
+	({ body }) => {
+		// only runs for correctly signed requests
+	}
+)
+```
+
+When `verify` returns `false`, the answer is
+`401 { error: 'Invalid signature', issues: [...] }` and `onEvent` gets
+`validation.target: 'signature'`.
+
+`hono-webhooks/signatures` has a verifier and a matching signer per provider:
+
+| Scheme                                  | Header                                  | Signed content      |
+| --------------------------------------- | --------------------------------------- | ------------------- |
+| `github`                                | `x-hub-signature-256: sha256=<hex>`     | body                |
+| `shopify`                               | `x-shopify-hmac-sha256: <base64>`       | body                |
+| `stripe`                                | `stripe-signature: t=<unix>,v1=<hex>`   | `<t>.<body>`        |
+| `hmac({ header, encoding, prefix?, hash? })` | any header, hex or base64, SHA-1/256/512 | body          |
+
+- `scheme.verify(secret)` gives a `verify` function. `secret` is a string or
+  `(c) => string | Promise<string>`, so it can come from `c.env`. An empty
+  secret throws (a 500), instead of silently accepting or rejecting everything.
+- `stripe.verify(secret, { toleranceSeconds })` also rejects timestamps more
+  than 300 seconds away by default, and accepts any matching `v1` so secret
+  rotation works.
+- `scheme.sign(rawBody, secret)` returns the headers the provider would send,
+  for tests and the CLI.
+- Signatures are compared with `crypto.subtle.verify`, which runs in constant
+  time. Everything uses Web Crypto, so it works on every runtime.
+
+For another provider, write the function yourself:
+
+```ts
+verify: async ({ c, rawBody, headers }) =>
+	headers['x-token'] === c.env.WEBHOOK_TOKEN
+```
+
 ## Mounting
 
 `createWebhooks(webhooks, options?)` returns a Hono app. Mount it under a
@@ -255,13 +316,17 @@ defineWebhook({ method: 'POST', path: '/orders/:id' }, async ({ params }) => {
 ```
 
 `onError` changes the response for any error, including 404 and 405. Return a
-`Response`, or nothing to fall back to the default. `console.error` is only
-called when you don't pass `onError`.
+`Response`, or nothing to fall back to the default.
+
+The default 500 response logs the error with `console.error`. Pass
+`logErrors: false` when you log errors yourself, in `onError` or `onEvent`,
+so they aren't logged twice.
 
 ```ts
 import { WebhookValidationError } from 'hono-webhooks'
 
 createWebhooks(webhooks, {
+	logErrors: false,
 	onError(error, c) {
 		if (error instanceof WebhookValidationError) {
 			return c.json({ type: 'validation', target: error.target, issues: error.issues }, 422)
@@ -283,7 +348,7 @@ createWebhooks(webhooks, {
 		logger.info('webhook', {
 			route: event.route, // '/orders/:id', undefined for a 404
 			method: event.method,
-			path: event.path, // '/webhooks/orders/42'
+			path: event.path, // '/orders/42', relative to the mount point
 			status: event.status,
 			durationMs: event.durationMs
 		})
@@ -295,86 +360,128 @@ createWebhooks(webhooks, {
 | ------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
 | `c`                                        | The Hono context, e.g. `c.req.header('user-agent')`                                                  |
 | `route`                                    | Matched path pattern, `undefined` for a 404                                                          |
-| `method`, `path`                           | Request method and path                                                                              |
-| `status`, `durationMs`                     | Response status and time spent in the webhooks app                                                   |
-| `params`, `query`, `headers`, `body`, `rawBody` | Each is set once it passed validation, so a request that fails on `body` still reports `params` |
+| `method`, `path`                           | Request method, and path relative to the mount point (`/orders/42`). The full path is `c.req.path` |
+| `status`, `durationMs`                     | Response status, and time spent in the webhooks app in fractional milliseconds                      |
+| `params`, `query`, `headers`               | `Record<string, unknown>`: the schema output, or the raw strings without a schema                    |
+| `body`, `rawBody`                          | Parsed body and raw body                                                                             |
 | `response`                                 | What the handler returned, unless it returned a `Response`                                           |
 | `error`                                    | Whatever was thrown                                                                                  |
-| `validation`                               | `{ target, issues }` when a request part or the response failed its schema                           |
+| `validation`                               | `{ target, issues }` when a request part, the signature or the response failed                      |
+
+Each request part is set once it has passed validation, so a request that
+fails on `body` still reports `params`.
+
+### Summaries and issue messages
+
+`summarizeEvent(event)` flattens an event into a JSON-safe record for logs or
+a database table:
+
+```ts
+import { formatIssues, summarizeEvent } from 'hono-webhooks'
+
+summarizeEvent(event)
+// {
+//   route: '/orders/:id', method: 'POST', path: '/orders/42', status: 400,
+//   durationMs: 1.37,                // rounded to two decimals
+//   ip: '203.0.113.9',               // x-forwarded-for, x-real-ip or cf-connecting-ip
+//   userAgent: 'Shopify-Captain-Hook',
+//   params: { id: '42' }, query: {}, body: null, response: null,
+//   error: null,                     // or { name, message, stack }
+//   validation: {
+//     target: 'body',
+//     message: 'total: Expected number',
+//     issues: [{ path: 'total', message: 'Expected number' }]
+//   }
+// }
+```
+
+- Missing values are `null`, never `undefined`.
+- Request headers are left out on purpose, because they carry signatures and
+  credentials.
+- `ip` comes from headers the client can set, so only trust it behind a
+  proxy that overwrites them.
+
+`formatIssues(issues)` turns Standard Schema issues into one line, like
+`total: Expected number; items.0.id: Required`.
 
 `onEvent` isn't awaited, so a slow database write doesn't delay the response.
 When it returns a promise, the promise is passed to
 `c.executionCtx.waitUntil()` on runtimes that have one (Cloudflare Workers,
 Vercel Edge), and a rejection is logged instead of crashing the request.
 
-## Recipes
+`onEvent` is called inside the request's async context, before the response
+is returned. The active OpenTelemetry span, `AsyncLocalStorage` values and
+anything set up in [`around`](#wrapping-requests-with-around) are available
+there, so log lines written in `onEvent` attach to the request.
 
-### Stripe signature verification
+### Wrapping requests with `around`
 
-`rawBody` is the exact payload Stripe signed.
+`around` wraps every request, including 404s and 405s, and already knows the
+matched route. Use it for anything that has to surround the whole request:
+a tracing span, an `AsyncLocalStorage` scope, a timer. Call `next()` to
+handle the request; it returns the response and runs `onEvent` inside your
+wrapper.
 
 ```ts
-import Stripe from 'stripe'
-import { HTTPException } from 'hono/http-exception'
+createWebhooks(webhooks, {
+	around: async ({ c, route, method }, next) => {
+		const res = await next()
+		console.log(method, route ?? '(no route)', res.status)
+		return res
+	}
+})
+```
+
+`route` is the pattern relative to the mount point (`/orders/:id`), or
+`undefined` for a 404. If `around` returns a response without calling
+`next()`, the request isn't handled and `onEvent` doesn't run.
+
+## Recipes
+
+### Stripe events
 
-const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)
+The body schema only runs on verified requests. `constructEventAsync` from
+the Stripe SDK works too, with `rawBody`, if you'd rather use their event
+types.
+
+```ts
+import { stripe } from 'hono-webhooks/signatures'
 
 export const stripeEvents = defineWebhook(
 	{
 		method: 'POST',
 		path: '/stripe',
-		headers: z.object({ 'stripe-signature': z.string() })
+		verify: stripe.verify(process.env.STRIPE_WEBHOOK_SECRET!),
+		body: z.object({
+			id: z.string(),
+			type: z.string(),
+			data: z.object({ object: z.record(z.string(), z.unknown()) })
+		})
 	},
-	async ({ headers, rawBody }) => {
-		let event: Stripe.Event
-		try {
-			event = await stripe.webhooks.constructEventAsync(
-				rawBody,
-				headers['stripe-signature'],
-				process.env.STRIPE_WEBHOOK_SECRET!
-			)
-		} catch {
-			throw new HTTPException(400, { message: 'Invalid signature' })
-		}
-		if (event.type === 'checkout.session.completed') {
-			await fulfil(event.data.object)
+	async ({ body }) => {
+		if (body.type === 'checkout.session.completed') {
+			await fulfil(body.data.object)
 		}
 		return { received: true }
 	}
 )
 ```
 
-### GitHub signature verification (Web Crypto, any runtime)
+### GitHub events
 
 ```ts
-async function hmacSha256Hex(secret: string, payload: string) {
-	const key = await crypto.subtle.importKey(
-		'raw',
-		new TextEncoder().encode(secret),
-		{ name: 'HMAC', hash: 'SHA-256' },
-		false,
-		['sign']
-	)
-	const signature = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(payload))
-	return [...new Uint8Array(signature)].map((b) => b.toString(16).padStart(2, '0')).join('')
-}
+import { github } from 'hono-webhooks/signatures'
 
 export const githubPush = defineWebhook(
 	{
 		method: 'POST',
 		path: '/github',
-		headers: z.object({
-			'x-github-event': z.string(),
-			'x-hub-signature-256': z.string()
-		})
+		verify: github.verify((c) => c.env.GITHUB_WEBHOOK_SECRET),
+		headers: z.object({ 'x-github-event': z.string() }),
+		body: z.object({ ref: z.string().optional() })
 	},
-	async ({ c, headers, rawBody, body }) => {
-		const expected = `sha256=${await hmacSha256Hex(c.env.GITHUB_WEBHOOK_SECRET, rawBody)}`
-		// Use a constant-time compare in production, e.g. crypto.timingSafeEqual on Node.
-		if (expected !== headers['x-hub-signature-256']) {
-			throw new HTTPException(401, { message: 'Invalid signature' })
-		}
-		// body is the parsed JSON
+	({ headers, body }) => {
+		if (headers['x-github-event'] === 'push') deploy(body.ref)
 	}
 )
 ```
@@ -398,21 +505,20 @@ defineWebhook(
 ### Storing every call
 
 ```ts
+import { summarizeEvent } from 'hono-webhooks'
+
 createWebhooks(webhooks, {
-	onEvent: (e) =>
-		db.insert(webhookCalls).values({
-			route: e.route ?? null,
-			path: e.path,
-			method: e.method,
-			statusCode: e.status,
-			durationMs: Math.round(e.durationMs),
-			body: e.body ?? null,
-			responseBody: e.response ?? null,
-			errorMessage: e.error instanceof Error ? e.error.message : null,
-			validationError: e.validation ?? null,
-			ipAddress: e.c.req.header('x-forwarded-for')?.split(',')[0]?.trim() ?? null,
-			userAgent: e.c.req.header('user-agent') ?? null
+	logErrors: false, // errors are stored below instead
+	onEvent: async (e) => {
+		if (e.route === '/health') return
+		const call = summarizeEvent(e)
+		await db.insert(webhookCalls).values({
+			...call,
+			errorMessage: call.error?.message ?? null,
+			errorStack: call.error?.stack ?? null,
+			validationError: call.validation?.message ?? null
 		})
+	}
 })
 ```
 
@@ -433,9 +539,45 @@ createWebhooks(webhooks, {
 })
 ```
 
-For traces, add a tracing middleware (for example
-[`@hono/otel`](https://github.com/honojs/middleware/tree/main/packages/otel))
-on the parent app before `app.route('/webhooks', ...)`.
+### OpenTelemetry traces
+
+One span per request, named by the route pattern (low cardinality), with
+`onEvent` logs attached to it:
+
+```ts
+import { SpanKind, SpanStatusCode, trace } from '@opentelemetry/api'
+
+const tracer = trace.getTracer('webhooks')
+
+createWebhooks(webhooks, {
+	around: ({ c, route, method }, next) =>
+		tracer.startActiveSpan(
+			`webhook ${method} ${route ?? 'unmatched'}`,
+			{
+				kind: SpanKind.SERVER,
+				attributes: {
+					'http.request.method': method,
+					'http.route': route ?? 'unmatched',
+					'url.path': c.req.path
+				}
+			},
+			async (span) => {
+				try {
+					const res = await next()
+					span.setAttribute('http.response.status_code', res.status)
+					if (res.status >= 500) span.setStatus({ code: SpanStatusCode.ERROR })
+					return res
+				} finally {
+					span.end()
+				}
+			}
+		),
+	onEvent: (e) => {
+		// trace.getActiveSpan() is the span above
+		if (e.error instanceof Error) trace.getActiveSpan()?.recordException(e.error)
+	}
+})
+```
 
 ### Skipping noise
 
@@ -468,26 +610,69 @@ app.route('/webhooks', webhooks)
 
 Hono's `showRoutes(app)` from `hono/dev` prints every route at startup.
 
+## Describing webhooks
+
+`describeWebhooks(appOrArray)` returns one entry per webhook, with JSON
+Schemas from any library that implements
+[Standard JSON Schema](https://standardschema.dev) (Zod 4.2+ does). Use it for
+an admin page, docs or an OpenAPI document:
+
+```ts
+import { describeWebhooks } from 'hono-webhooks'
+
+describeWebhooks(webhooks)
+// [{
+//   method: 'POST',
+//   path: '/orders/:id',
+//   description: 'Order paid',
+//   verified: true,          // has a verify function
+//   bodyType: 'auto',
+//   jsonSchema: { params: null, query: null, headers: null, body: {...}, response: {...} }
+// }]
+
+describeWebhooks(webhooks, { target: 'openapi-3.0' }) // or 'draft-07'
+```
+
+Request parts use the schema's input side (what the sender sends), `response`
+its output side. A part is `null` when it has no schema, or when the library
+can't produce JSON Schema.
+
 ## Testing
 
-The webhooks app is a Hono app, so `request()` runs the full pipeline:
-routing, validation, handler and response.
+`testWebhook(webhook, input)` sends one request through a single webhook and
+returns the `Response`. It runs everything a real request does: signature
+check, validation, handler and response handling. Its input is typed from the
+webhook's schemas:
 
 ```ts
 import { expect, test } from 'bun:test'
-import { webhooks } from './webhooks'
-
-test('rejects an order without a total', async () => {
-	const res = await webhooks.request('/orders/42', {
-		method: 'POST',
-		headers: { 'content-type': 'application/json' },
-		body: JSON.stringify({})
+import { testWebhook } from 'hono-webhooks'
+import { shopify } from 'hono-webhooks/signatures'
+import { orderPaid } from './webhooks/order-paid'
+
+test('marks the order paid', async () => {
+	const res = await testWebhook(orderPaid, {
+		params: { orderId: '42' }, // filled into the path
+		query: { dryRun: 'true' },
+		body: { amount: 10, currency: 'DKK' }, // typed from the body schema
+		sign: (rawBody) => shopify.sign(rawBody, 'test-secret'),
+		env: { SHOPIFY_WEBHOOK_SECRET: 'test-secret' }
 	})
-	expect(res.status).toBe(400)
+	expect(res.status).toBe(200)
 })
 ```
 
-Pass bindings as the third argument: `webhooks.request(path, init, env)`.
+| Input     | Description                                                                                                  |
+| --------- | ------------------------------------------------------------------------------------------------------------ |
+| `params`  | Filled into the path pattern. Use `path` instead for wildcard patterns.                                      |
+| `query`, `headers` | String records.                                                                                     |
+| `body`    | A string is sent as is. Anything else is sent as JSON, or url-encoded when `bodyType` is `'form'`.            |
+| `sign`    | Gets the exact raw body and returns headers to add, e.g. `(raw) => github.sign(raw, secret)`.                 |
+| `env`     | Bindings, available as `c.env`.                                                                              |
+| `options` | `createWebhooks` options, e.g. `{ onEvent }`.                                                                |
+
+To test a whole webhooks app with its routing, use Hono's `request()`:
+`webhooks.request('/orders/42', init, env)`.
 
 ## CLI
 
@@ -499,28 +684,42 @@ Commands:
   schema <path>             Print the JSON Schemas of the webhooks at <path>
   test <method> <path>      Send a request through the webhooks app
 
+Options:
+  -r, --preload <module>    Import a module first (e.g. to load secrets), repeatable
+
 Options for test:
   -b, --body <text>         Request body (JSON sets content-type: application/json)
   -q, --query <params>      Query string, e.g. "a=1&b=2"
   -H, --header <k: v>       Request header, repeatable
+  -s, --sign <scheme>       Sign the body: github, shopify, stripe
+  -e, --secret-env <name>   Environment variable holding the signing secret
 ```
 
-`<module>` is a file that exports the `createWebhooks()` result, as default or
-as any named export.
+`<module>` exports either a `createWebhooks()` app or an array of webhooks, as
+default or as any named export. With an array, the CLI builds the app itself,
+so it can point straight at the file that lists your webhooks.
 
 ```bash
 bunx hono-webhooks ./src/webhooks/index.ts list
 bunx hono-webhooks ./src/webhooks/index.ts schema /orders/:id
 bunx hono-webhooks ./src/webhooks/index.ts test POST /orders/42 -b '{"total":10}' -H 'x-api-key: dev'
+
+# Load secrets first, then sign the body like Shopify would
+bunx hono-webhooks ./src/webhooks/index.ts test POST /shopify/orders -b '{"id":1}' \
+  --preload ./src/secrets.ts --sign shopify --secret-env SHOPIFY_WEBHOOK_SECRET
 ```
 
 - `test` sends a real request through the webhooks app (without the parent
   app's middleware) and exits with code 1 on a 4xx or 5xx response.
-- `schema` prints JSON Schema for libraries that implement
-  [Standard JSON Schema](https://standardschema.dev) (Zod 4.2+ does).
+- `--preload` imports modules in order, before the webhooks module. It takes
+  a file path or a package name, and works the same under Bun and Node.
+- `--sign` signs the exact `--body` with the secret read from the environment
+  variable named by `--secret-env`, after preloading, so a preloaded module
+  can set it.
+- `schema` prints the JSON Schemas from
+  [`describeWebhooks`](#describing-webhooks).
 - The CLI imports your TypeScript file. That works under Bun, and under Node
-  22.18+ which strips types natively. If the module needs setup first (loading
-  secrets, for example), preload it: `bun --preload ./src/secrets.ts x hono-webhooks ...`.
+  22.18+ which strips types natively.
 
 ## API reference
 
@@ -529,17 +728,34 @@ import {
 	defineWebhook, // (config, handler) => Webhook
 	createWebhooks, // (webhooks, options?) => WebhooksApp  (a Hono app + .webhooks)
 	createWebhookFactory, // <E extends Env>() => { defineWebhook, createWebhooks }
-	WebhookValidationError // extends HTTPException; .target, .issues
+	WebhookValidationError, // extends HTTPException; .target, .issues
+	describeWebhooks, // (appOrArray, { target? }) => WebhookDescription[]
+	testWebhook, // (webhook, input?) => Promise<Response>
+	summarizeEvent, // (event) => WebhookEventSummary, flat and JSON-safe
+	formatIssues // (issues) => 'total: Expected number; ...'
 } from 'hono-webhooks'
 
+import {
+	github,
+	shopify,
+	stripe, // each: .verify(secret, options?) and .sign(rawBody, secret, options?)
+	hmac // (options) => a scheme like the ones above
+} from 'hono-webhooks/signatures'
+
 import type {
 	Webhook,
 	WebhookConfig,
 	WebhookInput,
 	WebhookResult,
 	WebhookEvent,
+	WebhookEventSummary,
+	WebhookDescription,
+	TestWebhookInput,
 	WebhooksOptions,
+	WebhookRequestInfo,
 	WebhooksApp,
+	Verify,
+	VerifyInput,
 	WebhookMethod,
 	BodyType,
 	ValidationTarget,
@@ -550,6 +766,14 @@ import type {
 
 Use `Webhook` to type a list: `const all: Webhook<AppEnv>[] = [a, b]`.
 
+## Upgrading from 0.1
+
+- `event.path` is relative to the mount point (`/orders/42`), like
+  `event.route`. Use `event.c.req.path` for the full path.
+- Passing `onError` no longer turns off `console.error` for the default 500
+  response. Pass `logErrors: false` for that.
+- `hono` 4.8 or newer is required.
+
 ## Migrating from `createHttpRoute`
 
 For code that used the in-app `lib/webhook` this package came from:
@@ -560,10 +784,10 @@ For code that used the in-app `lib/webhook` this package came from:
 | `reqBodySchema`, `reqQuerySchema`, ...         | `body`, `query`, `headers`, `params`, `response`                              |
 | `z.string()` body switches to text parsing     | Parsing follows `Content-Type`; set `bodyType: 'text'` to force it           |
 | `z.any()` body skips the content-type check    | No content-type check anymore; leave `body` out and read `body` / `rawBody`  |
-| `rawBody: true`                                | Always available as `rawBody`; the body is also parsed                        |
+| `rawBody: true` + checking the signature by hand | `verify: shopify.verify(secret)` (or your own function); `rawBody` is always passed too |
 | `request` in the handler                       | `c.req.raw`                                                                    |
 | `useHonoWebhooks(app)`                         | `app.route('/webhooks', createWebhooks(webhooks, { onEvent }))`               |
-| Built-in OTel span, logger, `recordWebhookCall` | `onEvent` (see [Recipes](#recipes)) and tracing middleware                    |
+| Built-in OTel span, logger, `recordWebhookCall` | `around` for the span, `onEvent` for logs and storage (see [Recipes](#recipes)) |
 | `HEAD` / custom methods in `method`            | `GET` routes answer `HEAD` automatically                                      |
 | Response schema mismatch recorded as 500       | Recorded as `event.validation` with the real status                           |
 | Malformed JSON without a schema → `body: null` | `400 Invalid body`. Use `bodyType: 'text'` to accept anything                 |