Most Express webhook bugs are not network bugs. They are middleware-order bugs. If a JSON parser runs before signature verification, your hash check fails even though the request is legitimate. Local testing should prove raw-byte verification, route scoping, and safe comparisons before you deploy.
Use express.raw only where webhooks land
Do not replace your entire app parser stack. Limit express.raw({ type: '*/*' }) to webhook routes so normal API endpoints still use express.json(). Scoped middleware keeps behavior predictable and avoids accidental side effects.
app.post('/webhooks/stripe', express.raw({ type: '*/*' }), stripeHandler);
app.use(express.json());Verify first, parse second
Read signature headers, compute the expected digest from the raw buffer, and compare with crypto.timingSafeEqual. Only after validation should you parse JSON and run business logic. This order is the core reliability rule for Express webhooks.
Common implementation trap: global body parser
A global parser that runs before webhook routes silently mutates payload bytes. Your logs still show valid JSON, but provider signatures fail. The fix is route-level raw parsing and explicit middleware order in your app bootstrap.
Local testing checklist
- Start the Express server locally.
- Expose it with
npx portpreview 3000. - Configure the provider webhook URL to the tunnel domain.
- Replay events and confirm signature pass/fail behavior.
- Simulate retries and ensure idempotent processing.
Handle retries and duplicate event delivery
Providers retry when responses are slow or non-2xx. Never tie side effects directly to delivery count. Persist event IDs and short-circuit duplicates. The combination of signature verification + idempotency gives you both authenticity and consistency.
Where to go deeper
If teammates are new to the concept, start with localhost tunneling basics and practical local webhook debugging. For the cryptography model, review signature verification guidance. For duplicate-safe handlers, read retry and idempotency patterns. To get early access to streamlined tooling, join the PortPreview waitlist.