webhook-hardening

name	webhook-hardening
description	Harden a commerce webhook handler: verify the provider signature with a constant-time compare BEFORE parsing the body, then de-duplicate retried deliveries by provider event id. Use when writing or reviewing any Stripe/Square/Shopify webhook receiver. Two invariants (verify-before-parse, event-id idempotency) that are non-negotiable.

Webhook Hardening

Two non-negotiable invariants for every webhook handler this plugin scaffolds. Both are enforced by the commerce-gold-standard-rubric (dimensions 2 and 3).

Invariant 1 — verify (constant-time) BEFORE parsing

1. Read the raw body — do not parse or re-serialize it first (that changes bytes and invalidates the signature).
2. Recompute the signature and compare with safeSignatureEqual from templates/shared/webhook-verify.ts — a constant-time compare. A plain === leaks timing an attacker uses to forge signatures.
3. On mismatch, drop the request (4xx). Only a verified request proceeds.

Per-provider scheme:

Provider	Header	Signed over	Notes
Stripe	Stripe-Signature	payload + whsec_ secret	5-min timestamp tolerance guards replays
Square	x-square-hmacsha256-signature	signatureKey + notificationUrl + rawBody	HMAC-SHA256
Shopify	X-Shopify-Hmac-Sha256	rawBody	base64 HMAC-SHA256

Invariant 2 — idempotency (exactly-once)

Providers retry deliveries and do not guarantee ordering. Before any side effect:

1. Extract the provider event id (Stripe event.id, Square event_id, Shopify delivery id).
2. await store.seen(eventId) — if true, return 2xx and stop (already processed).
3. Do the work, then await store.remember(eventId, ttl).

Use an IdempotencyStore (templates/shared/idempotency-store.ts). On a static tier the store is KV-backed (Upstash / Vercel KV) behind a serverless function — never a process-memory Set (a recycled invocation loses it and re-processes) and never browser state.

Also

• Return 2xx fast, then process heavy work async — providers time out and retry on a slow 2xx.
• Store only safe fields (card type / last4 / expiry), never the PAN.
• Mutating API calls carry their own idempotency key (separate from webhook dedup) — see payment-lifecycle-contract.