Stripe Webhooks

You are a backend developer integrating Stripe webhooks. The user wants to receive, verify, and process Stripe webhook events securely with proper signature validation.

What to check first

• Run npm list stripe to confirm the Stripe Node library is installed (version 8.0.0+)
• Verify your Stripe webhook signing secret is stored in environment variables (e.g., STRIPE_WEBHOOK_SECRET)
• Check your server framework supports raw request body parsing (Express needs express.raw() middleware)

Steps

1. Install Stripe: npm install stripe
2. Set up a raw body parser middleware in Express — Stripe signature verification requires the raw request body, not parsed JSON
3. Create a webhook endpoint that accepts POST requests at a path like /webhook or /api/webhooks/stripe
4. Extract the Stripe signature from the stripe-signature header using request.headers['stripe-signature']
5. Verify the webhook signature using stripe.webhooks.constructEvent() — this validates the request came from Stripe
6. Extract the event type from the verified event object (e.g., event.type === 'charge.succeeded')
7. Handle specific event types with dedicated switch cases or conditional logic
8. Return a 200 status code immediately to acknowledge receipt, then process events asynchronously if needed

Code

const express = require('express');
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

const app = express();

// Raw body parser MUST come before JSON parser for webhook route
app.post(
  '/webhook',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const sig = req.headers['stripe-signature'];
    const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET;

    let event;

    try {
      // Verify signature and construct event
      event = stripe.webhooks.constructEvent(
        req.body,
        sig,
        webhookSecret
      );
    } catch (err) {
      console.error(`Webhook signature verification failed: ${err.message}`);
      return res.status(400).send(`Webhook Error: ${err.message}`);
    }

    // Acknowledge receipt immediately
    res.status(200).json({ received: true });

    // Process event asynchronously
    try {
      switch (event.type) {
        case 'charge.succeeded': {
          const charge = event.data.object;
          console.log(`Charge succeeded: ${charge.id} for $${charge.amount / 100}`);
          // Update database, send confirmation email, etc.
          break;
        }

        case 'charge.failed': {
          const charge = event.data.object;
          console.log(`Charge failed: ${charge.id}`);
          // Notify user, retry logic, etc.
          break;
        }

        case 'customer.subscription.updated': {

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change