integrating-stripe-webhooks

Stripe webhook signature verification requires the raw request body before any middleware parses it. Configure your framework (Express, Fastify) to preserve the raw body, then pass it to stripe.webhooks.constructEvent() with your signing secret. This prevents 400 signature errors and ensures webhooks process correctly.

This error occurs when JSON parsing middleware runs before Stripe's signature verification, consuming the raw body. Move raw body parser middleware before any other parsers and before your webhook route handler. Framework-specific solutions differ: Fastify uses raw body options, Express uses body-parser with verify callbacks.

Stripe's TypeScript definitions may omit subscription period fields like `current_period_start` and `current_period_end`. Access them via `subscription.items.data[0]` to retrieve billing cycle dates, or apply type workarounds to extend Stripe's type definitions with missing subscription attributes.

Both frameworks support Stripe webhooks, but raw body handling differs. Express requires body-parser with a verify callback; Fastify uses rawBody plugin or request hooks. The core signature verification step with stripe.webhooks.constructEvent() remains identical across frameworks.

Register Stripe webhook routes under your API prefix—typically `/api/webhooks` or `/webhooks`—ensuring they're accessible to Stripe's servers. Verify the route matches your Stripe dashboard webhook URL exactly, including protocol and domain, to prevent event delivery failures.

Test webhook handling by inspecting the parsed event object for subscription data, verifying `event.data.object.items.data[0]` contains period fields, and confirming signature verification passes. Use Stripe's webhook testing tools or event logs to simulate real subscription.updated and customer.subscription.updated events.