integrating-stripe-webhooks

This skill serves as a specialized guide for developers struggling with Stripe webhook integration, particularly when dealing with raw request body requirements. Because many modern web frameworks—such as Fastify, Express, and FastAPI—automatically parse JSON request bodies by default, the signature verification process for Stripe often fails, resulting in 'Raw body not available' or 400 signature verification errors. This skill provides precise, framework-specific code patterns to access raw buffers before middleware interference occurs, ensuring secure communication with the Stripe API.

Beyond body parsing, this skill addresses common TypeScript type mismatches that frequently plague subscription-based applications. Developers often encounter errors when attempting to access properties like 'current_period_start' directly on a subscription object, failing to realize these fields reside deeper in the subscription item data structure. By following the documented patterns, developers can avoid these runtime errors and successfully process complex Stripe events.

• Provides boilerplate patterns for raw body configuration in Fastify, Express, and FastAPI to ensure successful constructEvent() verification.

• Offers detailed strategies for debugging 404 errors caused by improper route registration relative to API prefixes.

• Supplies robust methods for accessing subscription period dates, including fallback logic for when specific fields are missing from the root subscription object.

• Includes tips for URL-encoding dynamic parameters in checkout URLs to prevent URI format validation failures.

• Always configure raw body parsers before any JSON parsing middleware.

• When encountering TypeError regarding subscription periods, inspect subscription.items.data[0] rather than the root.

• Ensure the STRIPE_WEBHOOK_SECRET environment variable is correctly loaded and verified for every request.

• Use the provided implementation checklist to ensure comprehensive handling of webhook events, including returning 200 responses promptly to prevent event retries.

• Note that this skill is strictly for backend webhook processing; frontend Stripe Elements or general checkout session management are outside its scope.