webhook-architecture

Use a 3-layer pattern: a thin controller extracts the raw body and signature headers, a webhook service verifies the signature and routes events by type, and business services execute domain logic. Enable rawBody in NestFactory and exclude webhook routes from the global API prefix.

Use the provider SDK: stripe.webhooks.constructEvent for Stripe or paddle.webhooks.unmarshal for Paddle, passing the raw request body and signature header. Without an SDK, compute an HMAC-SHA256 over the raw body and compare with crypto.timingSafeEqual.

Providers retry on non-2xx responses, causing duplicate processing and multiplied server load for one broken event. Return 200 for all outcomes, store failures internally, and reserve non-200 codes only for signature verification failures (401) or rate limiting (429).

Track processed event IDs in a database table and check before handling each event, or use upsert with the external event ID as a unique key. For high throughput above thousands per minute, use Redis SETNX with a TTL for faster deduplication lookups.

Parsing and re-serializing JSON alters whitespace, key ordering, and unicode escapes, producing different bytes than the provider signed. Always compute the HMAC over the original raw request body buffer, which requires rawBody: true in NestJS.

Manual retry via admin endpoints suffices below roughly 100 failures per day. For medium volumes, use BullMQ with exponential backoff starting at 30 seconds across 5 attempts; high volumes above 10,000 per day warrant a dedicated worker process.