FRD: Webhook Handling Package

Document Summary

Field	Details
Feature Name	Webhook Handling Package
Status	Draft
Owner	David Holmes
Contributors	Engineering
Target Release	v2.0.0
Related Links	ADR-051 (Provider Pattern), ADR-065 (Webhook Handling), ADR-027 (Default Tech Stack)
Last Updated	2026-05-26
Open Source Libraries	standardwebhooks, svix

Verify-before-parse helpers, replay protection, normalized event envelopes, and job queue handoff for vendor webhooks. Implements the pattern defined in ADR-065.

---

Introduction

Overview

ADR-065 defines a rigorous webhook handling pattern: verify signature before parsing, reject replayed events, normalize vendor payloads into internal domain events, and acknowledge fast with async processing on a job queue. No implementation exists today. Each app reimplements signature verification with subtle differences, has inconsistent replay windows, and parses vendor payloads directly in handler code. This FRD defines a webhook-handling package that provides signature verification, replay protection, event normalization, and job queue dispatch as composable utilities.

Goals

• Provide verifyWebhookSignature() helpers for common vendor signature schemes (HMAC-SHA256, Stripe v1, Svix, raw HMAC).
• Implement replay protection with configurable tolerance window and event ID deduplication.
• Define a WebhookEvent normalized envelope type that all vendor payloads map to.
• Provide a createWebhookHandler() factory that composes verification, replay protection, normalization, and queue dispatch.
• Ship per-provider examples (Stripe, Resend, generic HMAC) demonstrating the full flow.
• Include a comprehensive test suite validating signature verification and replay rejection.

Non-Goals

• Implementing vendor-specific payload parsers for every possible webhook source.
• Building HTTP route handlers for specific frameworks (Express, Hono, Astro) — the package provides framework-agnostic utilities.
• Implementing the job queue itself (see FRD: Jobs/Queue Provider).
• Building a webhook management UI or dashboard.
• Outbound webhook sending.

---

Scope

In Scope

Area	Description
Signature verification	verifyWebhookSignature() supporting HMAC-SHA256, Stripe v1= scheme, Svix, and raw HMAC
Replay protection	ReplayGuard with configurable max-age window and event ID deduplication
Event envelope	WebhookEvent normalized type with { id, type, vendor, data, receivedAt, verified }
Handler factory	createWebhookHandler({ verify, normalize, dispatch }) composing the full pipeline
Provider examples	Example normalizers for Stripe, Resend, and generic HMAC webhooks
Test utilities	createTestWebhookPayload() helpers for generating signed test payloads
Documentation	Storybook docs with per-vendor integration examples

Out of Scope

Area	Reason
Framework-specific route handlers	Apps integrate the utilities into their own routing layer
Job queue implementation	Covered by FRD: Jobs/Queue Provider; this package dispatches to a QueueProvider
Vendor-specific payload parsing for all vendors	Only provide examples; each vendor adapter handles its own parsing per ADR-051
Outbound webhook sending	Separate concern; this package is for inbound webhooks only
Webhook registration/subscription management	Vendor-side configuration, not a library responsibility

---

Users and Pain Points

User Groups

User	Description	Needs
App developers	Engineers building webhook endpoints	Composable verify-before-parse utilities that follow ADR-065
QA engineers	Testers validating webhook processing	Test payload generators with valid signatures for integration tests
Security reviewers	Engineers auditing webhook handlers	A single, auditable verification path with no bypass

Pain Points

User	Pain Point	Impact
App developers	Each app reimplements HMAC verification with subtle timing-safe comparison bugs	Security vulnerabilities from incorrect signature verification
App developers	No replay protection — events can be replayed to trigger duplicate processing	Data corruption from double-processing (duplicate charges, duplicate emails)
App developers	Vendor payloads leak into app code — handlers parse Stripe JSON directly	Vendor lock-in; changing payment providers requires rewriting handlers
Security reviewers	No standard verification path to audit — each handler is unique	Inconsistent security posture across webhook endpoints

---

Definitions

Term	Definition
Signature verification	Cryptographic proof that the payload was sent by the claimed vendor and was not tampered with
Replay attack	Re-sending a previously valid webhook payload to trigger duplicate processing
Replay guard	A mechanism that rejects events older than a tolerance window or already seen by event ID
Event envelope	The normalized wrapper around a webhook payload with standard metadata fields
Timing-safe comparison	A string comparison that takes constant time regardless of where a mismatch occurs, preventing timing attacks
Normalizer	A function that transforms a vendor-specific payload into the standard WebhookEvent envelope

---

Current State

Existing Behavior

ADR-065 documents the webhook handling pattern in detail but no code implements it. The auth provider (auth-provider.ts) includes a verifyWebhook() method, but it is provider-specific and not reusable across vendors. No shared signature verification, replay protection, or event normalization utilities exist.

Current Limitations

• No shared verifyWebhookSignature() utility — each app rolls its own HMAC check.
• No replay protection — handlers process every delivery, including retries and replays.
• No normalized event type — handlers parse raw vendor JSON with any types.
• No test payload generators — testing webhook handlers requires manual payload construction.
• No composable handler factory — the ADR-065 pattern must be implemented from scratch each time.

Existing Workarounds

• Apps use crypto.timingSafeEqual directly with hand-written HMAC logic.
• Some apps check a Stripe event timestamp but do not track event IDs for deduplication.
• Handlers type vendor payloads as any or use vendor SDK type imports.

---

Proposed Solution

Summary

Add a src/lib/webhooks/ directory containing signature verification utilities, a replay guard, a WebhookEvent envelope type, a composable handler factory, and test helpers. The package does not depend on any vendor SDK — vendor-specific signature schemes are implemented from primitives (crypto.createHmac). The handler factory composes verification, replay checking, normalization, and queue dispatch into a single pipeline.

Key Capabilities

• verifyWebhookSignature(payload, signature, secret, scheme) with built-in support for HMAC-SHA256, Stripe v1= timestamp scheme, and Svix.
• ReplayGuard class with configurable maxAgeMs (default 5 minutes) and in-memory event ID set with automatic expiry.
• WebhookEvent<T> envelope: { id, type, vendor, data: T, receivedAt, verified }.
• createWebhookHandler({ verifier, replayGuard, normalizer, dispatcher }) factory returning a (rawPayload, headers) => Promise<WebhookHandlerResult> function.
• createTestWebhookPayload(secret, payload, scheme) for generating correctly signed payloads in tests.

User Experience

End users are not directly affected. Webhook handling is a backend concern.

Developer Experience

Developers create a webhook handler by composing verification, normalization, and dispatch:

const handler = createWebhookHandler({
  verifier: { secret: process.env.STRIPE_WEBHOOK_SECRET, scheme: "stripe-v1" },
  replayGuard: { maxAgeMs: 300_000 },
  normalizer: stripeNormalizer,
  dispatcher: (event) => queue.enqueue("billing.webhook", { type: event.type, payload: event }),
});

Tests use createTestWebhookPayload to generate signed payloads without vendor SDKs.

---

Requirements

ID	Requirement	Priority	Notes
FR-001	Export verifyWebhookSignature() supporting HMAC-SHA256, Stripe v1, and Svix schemes	Must	-
FR-002	Export ReplayGuard with configurable max-age window and event ID deduplication	Must	-
FR-003	Export WebhookEvent<T> normalized envelope type	Must	-
FR-004	Export createWebhookHandler() factory composing verify, replay, normalize, and dispatch	Must	-
FR-005	Export createTestWebhookPayload() for generating signed test payloads	Must	-
FR-006	Signature verification uses timing-safe comparison	Must	Security requirement
FR-007	Export example normalizers for Stripe and Resend webhooks	Should	-

Priority Definitions

Priority	Meaning
Must	Required for this feature to ship.
Should	Important, but can be deferred if needed.
Could	Nice to have. Not required for initial release.

---

Functional Requirements

ID	Requirement	User Benefit	Priority
FUNC-001	verifyWebhookSignature(payload, signature, secret, "hmac-sha256") returns true for valid signatures	Standard HMAC verification without manual crypto code	Must
FUNC-002	verifyWebhookSignature with "stripe-v1" scheme parses the t= timestamp and v1= signature from the header	Stripe webhook verification without Stripe SDK	Must
FUNC-003	ReplayGuard.check(eventId, timestamp) rejects events older than maxAgeMs	Prevents replay attacks	Must
FUNC-004	ReplayGuard.check() rejects events with an already-seen ID within the window	Prevents duplicate processing	Must
FUNC-005	createWebhookHandler() returns 401 result for invalid signatures	Unverified payloads never reach app code	Must
FUNC-006	createWebhookHandler() returns 200 result and dispatches to the queue on success	Fast acknowledgment per ADR-065	Must
FUNC-007	createTestWebhookPayload() generates a payload with a valid signature for any supported scheme	Test webhook handlers without vendor sandboxes	Must
FUNC-008	ReplayGuard automatically evicts expired event IDs to prevent unbounded memory growth	Long-running servers stay healthy	Should

---

Non-Functional Requirements

ID	Requirement	Category	Priority
NFR-001	Signature verification uses crypto.timingSafeEqual to prevent timing attacks	Security	Must
NFR-002	Zero vendor SDK imports — verification is implemented from Node.js crypto primitives	Maintainability	Must
NFR-003	ReplayGuard memory usage is bounded — expired entries are evicted automatically	Performance	Must
NFR-004	Handler factory returns structured results (status code + body), not HTTP response objects	Compatibility	Must
NFR-005	All utilities work in Node.js and edge runtimes (no Buffer-only APIs)	Compatibility	Should
NFR-006	Signing secrets must never appear in error messages or logs	Security	Must

---

API / Interface Requirements

Public API

Name	Type	Description	Required
verifyWebhookSignature	function	(payload, signature, secret, scheme) => boolean	Yes
ReplayGuard	class	Configurable replay protection with check(eventId, timestamp)	Yes
WebhookEvent<T>	type	{ id, type, vendor, data: T, receivedAt, verified }	Yes
WebhookHandlerResult	type	{ status: number, body: string, event?: WebhookEvent }	Yes
createWebhookHandler	function	Factory composing verifier, replay guard, normalizer, dispatcher	Yes
createTestWebhookPayload	function	(secret, payload, scheme) => { body, headers }	Yes
SignatureScheme	type	"hmac-sha256" | "stripe-v1" | "svix"	Yes

Example Usage

import {
  createWebhookHandler,
  createTestWebhookPayload,
} from "@dmwd/design-system/webhooks";

// Production handler
const handler = createWebhookHandler({
  verifier: { secret: process.env.WEBHOOK_SECRET!, scheme: "hmac-sha256" },
  replayGuard: { maxAgeMs: 300_000 },
  normalizer: (verified) => ({
    id: verified.id,
    type: `billing.${verified.eventType}`,
    vendor: "stripe",
    data: verified.data,
    receivedAt: new Date().toISOString(),
    verified: true,
  }),
  dispatcher: async (event) => {
    await queue.enqueue("billing.webhook", { type: event.type, payload: event });
  },
});

// In a route handler
const result = await handler(rawBody, request.headers);
return new Response(result.body, { status: result.status });

// In tests
const { body, headers } = createTestWebhookPayload("test_secret", {
  id: "evt_123",
  eventType: "invoice.paid",
  data: { invoiceId: "inv_456" },
}, "hmac-sha256");

API Notes

• The handler factory returns a WebhookHandlerResult, not an HTTP Response, so it works with any framework.
• The normalizer function receives the parsed payload and returns a WebhookEvent — it is the boundary where vendor shapes become internal shapes.
• ReplayGuard is instantiated by the factory but can also be used standalone for custom handlers.

---

Accessibility Requirements

ID	Requirement	Notes
A11Y-001	Package is a backend utility with no UI — accessibility requirements do not apply	No UI components

Checklist

• Keyboard support is defined. (N/A — no UI)
• Focus behavior is defined. (N/A — no UI)
• Screen reader behavior is defined. (N/A — no UI)
• Color contrast requirements are met. (N/A — no UI)
• Reduced motion behavior is considered. (N/A — no UI)
• Semantic HTML expectations are documented. (N/A — no UI)
• ARIA usage is defined only where needed. (N/A — no UI)

---

Content and Documentation Requirements

ID	Requirement	Location	Priority
DOC-001	Storybook docs page explaining the webhook handling pattern and ADR-065 compliance	Storybook	Must
DOC-002	Inline JSDoc on every exported function and type	Source code	Must
DOC-003	Example: Stripe webhook handler using createWebhookHandler with queue dispatch	Storybook	Must
DOC-004	Example: Resend webhook handler	Storybook	Should
DOC-005	Example: testing a webhook handler with createTestWebhookPayload	Storybook	Must

---

Dependencies

Dependency	Type	Owner	Status	Notes
ADR-065 webhook handling	Architecture	Engineering	Ready	Defines the pattern this package implements
ADR-051 provider pattern	Architecture	Engineering	Ready	Webhook handlers sit inside provider wrapper folders
Node.js crypto module	Runtime	Node.js	Ready	Used for HMAC computation and timing-safe comparison
Jobs/queue provider	Library	Engineering	Not Started	Webhook handlers dispatch to the queue provider

---

Risks and Tradeoffs

Risk / Tradeoff	Impact	Mitigation
In-memory replay guard does not persist across server restarts	Brief window of duplicate processing after restart	Document that production deployments should use a persistent replay guard (Redis-backed)
Supporting multiple signature schemes increases code surface	More code to audit and maintain	Each scheme is a small, isolated function; the factory delegates to the matching verifier
Framework-agnostic design means apps must wire their own route handlers	Slightly more integration code per app	Provide copy-paste examples for Astro, Hono, and Express in documentation
Edge runtime compatibility requires avoiding Buffer-only APIs	Some Node.js crypto patterns need adaptation	Use Uint8Array and TextEncoder where possible; document Node.js-only fallbacks

---

Open Questions

ID	Question	Owner	Status	Resolution
Q-001	Should the ReplayGuard support a persistent backend (Redis) as a pluggable store, or only in-memory?	David Holmes	Open	—
Q-002	Should the package export framework-specific wrappers (e.g. createAstroWebhookRoute) or remain purely framework-agnostic?	David Holmes	Open	—
Q-003	Should the handler factory support multiple signature secrets for key rotation?	David Holmes	Open	—

---

Acceptance Criteria

ID	Criteria	Related Requirement
AC-001	verifyWebhookSignature() correctly verifies HMAC-SHA256, Stripe v1, and Svix signatures	FR-001
AC-002	verifyWebhookSignature() uses crypto.timingSafeEqual internally	FR-006, NFR-001
AC-003	ReplayGuard rejects events older than the configured maxAgeMs	FR-002, FUNC-003
AC-004	ReplayGuard rejects events with duplicate IDs within the window	FUNC-004
AC-005	createWebhookHandler() returns status 401 for invalid signatures	FUNC-005
AC-006	createWebhookHandler() returns status 200 and calls the dispatcher for valid events	FUNC-006
AC-007	createTestWebhookPayload() generates payloads that pass verifyWebhookSignature()	FR-005, FUNC-007
AC-008	Unit tests cover valid signatures, invalid signatures, replay rejection, and expired events	FR-001 through FR-006
AC-009	No vendor SDK is imported anywhere in the package	NFR-002
AC-010	Signing secrets do not appear in any error messages	NFR-006

---

LLM Handoff Instructions

Expected LLM Behavior

• Place all files under src/lib/webhooks/.
• Implement signature verification using Node.js crypto module only — no vendor SDK imports.
• Use crypto.timingSafeEqual for all signature comparisons.
• ReplayGuard should use a Map<string, number> with periodic cleanup of expired entries.
• The handler factory should return WebhookHandlerResult objects, not HTTP Response instances.
• createTestWebhookPayload must produce payloads that round-trip through verifyWebhookSignature.
• Add unit tests in webhook-handling.test.ts covering all verification schemes, replay scenarios, and handler composition.
• Reference ADR-065 in JSDoc comments.

LLM Should Not

• Import any vendor SDK (Stripe, Svix, etc.).
• Build framework-specific route handlers.
• Implement the job queue — only define the dispatcher callback type.
• Add runtime dependencies beyond Node.js built-ins.
• Store secrets in code or test fixtures (use well-known test values like "whsec_test").

---

Decision Log

Date	Decision	Reason	Owner
2026-05-26	Framework-agnostic handler returning result objects, not HTTP Responses	Works with Astro, Hono, Express, and edge runtimes without framework coupling	David Holmes
2026-05-26	In-memory replay guard as the default, with pluggable store as a future extension	Keeps initial implementation simple; most apps can tolerate brief replay windows on restart	David Holmes
2026-05-26	Support 3 signature schemes (HMAC-SHA256, Stripe v1, Svix) at launch	Covers the most common vendors; additional schemes are easy to add	David Holmes

---

Document History

Date	Author	Change
2026-05-26	David Holmes	Initial draft