integrating-stripe-webhooks

Integrating Stripe Webhooks

Overview

Stripe webhooks require raw request bodies for signature verification. Most web frameworks parse JSON automatically, breaking verification. This skill provides framework-specific solutions for the raw body problem and documents common TypeScript type mismatches.

When to Use

Use this skill when:

• Getting "Raw body not available" errors from Stripe webhooks
• Webhook signature verification fails with 400 errors
• Implementing new Stripe webhook endpoints
• Getting TypeError: Cannot read property 'current_period_start' from subscription events
• Webhooks return 404 (route registration issues)

Don't use for:

• General Stripe API integration (not webhooks)
• Frontend Stripe Elements implementation
• Stripe checkout session creation (use Stripe docs)

Quick Reference

Problem	Solution
Raw body not available	Configure custom body parser (see framework examples)
Signature verification fails	Use raw body bytes/buffer, not parsed JSON
404 on webhook endpoint	Register webhook route inside API prefix
current_period_start undefined	Access from subscription.items.data[0] not root
URI validation errors	URL-encode dynamic parameters with encodeURIComponent()

Critical: Raw Body Parsing

THE PROBLEM: Stripe's constructEvent() requires the exact bytes received to verify the signature. JSON parsing modifies the body, breaking verification.

THE SOLUTION: Access raw body before any parsing middleware.

Framework Examples

Node.js - Fastify (most common for new projects):

// In main server file, BEFORE registering routes
server.addContentTypeParser('application/json',
  { parseAs: 'buffer' },
  async (req: any, body: Buffer) => {
    req.rawBody = body;  // Store for webhooks
    return JSON.parse(body.toString('utf8'));  // Parse for other routes
  }
);

// In webhook handler
const rawBody = (request as any).rawBody;
const event = stripe.webhooks.constructEvent(
  rawBody, signature, webhookSecret
);