Why Your Stripe Webhooks Are Silently Failing (And How to Fix All of It)

The five mistakes that cause payment integrations to break in production — with no error messages to tell you why.

There’s a specific kind of dread that hits when you realize your payment system has been silently failing. Users paid. Stripe processed the charge. Your database still shows pending. You don’t know how long it’s been broken.

Stripe webhooks are how your server learns about events — payments succeeded, subscriptions renewed, cards expired. They’re asynchronous, they retry on failure, they can arrive out of order, and they can arrive multiple times. Most payment integration bugs don’t come from the Stripe API itself. They come from webhook handlers that look correct but aren’t.

Here are the five mistakes that cause Stripe webhooks to fail silently in production — and exactly how to fix each one.

1. You’re Verifying the Wrong Body

This is the most common cause of signature verification failures, and it produces the most confusing error message: No signatures found matching the expected signature for payload.

The problem: Express (and most frameworks) parse the request body before your handler runs. When you call stripe.webhooks.constructEvent() with req.body, you’re passing a JavaScript object that’s been serialized back to a string — and that re-serialized string doesn’t match what Stripe actually sent.

// Wrong — re-serializes differently than what Stripe sent
const event = stripe.webhooks.constructEvent(
  JSON.stringify(req.body),
  req.headers['stripe-signature'],
  process.env.STRIPE_WEBHOOK_SECRET
);

// Right — use the raw bytes Stripe actually sent
const event = stripe.webhooks.constructEvent(
  req.rawBody,
  req.headers['stripe-signature'],
  process.env.STRIPE_WEBHOOK_SECRET
);

To get req.rawBody in Express, you need to configure body parsing to save it:

app.use(
  express.raw({ type: 'application/json' })
);

Or if you need JSON parsing elsewhere:

app.use((req, res, next) => {
  if (req.originalUrl === '/webhooks/stripe') {
    express.raw({ type: 'application/json' })(req, res, next);
  } else {
    express.json()(req, res, next);
  }
});

In Next.js, you need to disable the default body parser for the webhook route:

export const config = {
  api: {
    bodyParser: false,
  },
};

2. You’re Using the Wrong Signing Secret

Stripe has separate signing secrets for test mode and live mode. They’re different values. If your production environment has the test webhook secret in STRIPE_WEBHOOK_SECRET, every signature verification fails — silently, with no indication of which secret is wrong.

Checklist:

Test mode secret starts with whsec_ — check your Stripe Dashboard → Developers → Webhooks → your endpoint → Signing secret
Live mode secret is a different value in a different section of the dashboard
Your production environment variables must contain the live mode secret
Your staging/development environment should use the test mode secret

If you’re using the Stripe CLI for local development (stripe listen --forward-to localhost:3000/webhooks), the CLI generates its own temporary signing secret that’s different from both — print it with stripe listen --print-secret.

3. You’re Not Handling Duplicate Events

Stripe guarantees at-least-once delivery — never exactly-once. The same event can arrive multiple times. If your webhook handler charges a customer, sends a confirmation email, or provisions access, and it runs twice on the same event, you have a real problem.

The fix is idempotency: check if you’ve already processed an event before acting on it.

app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), async (req, res) => {
  const event = stripe.webhooks.constructEvent(
    req.body,
    req.headers['stripe-signature'],
    process.env.STRIPE_WEBHOOK_SECRET
  );

  // Check if we've already processed this event
  const existing = await db.query(
    'SELECT id FROM processed_webhook_events WHERE stripe_event_id = $1',
    [event.id]
  );

  if (existing.rows.length > 0) {
    return res.json({ received: true }); // Already handled
  }

  // Process the event
  await handleEvent(event);

  // Record that we've processed it
  await db.query(
    'INSERT INTO processed_webhook_events (stripe_event_id, type, processed_at) VALUES ($1, $2, NOW())',
    [event.id, event.type]
  );

  res.json({ received: true });
});

The table you need:

CREATE TABLE processed_webhook_events (
  stripe_event_id TEXT PRIMARY KEY,
  type TEXT NOT NULL,
  processed_at TIMESTAMPTZ DEFAULT NOW()
);

4. You’re Doing Too Much Work Synchronously

Stripe waits 10 seconds for a 2xx response. If your handler doesn’t respond in time, Stripe marks the delivery as failed and retries.

The mistake: putting heavy processing — sending emails, calling third-party APIs, generating PDFs, running background jobs — directly in the webhook handler before responding.

The pattern that breaks:

app.post('/webhooks/stripe', async (req, res) => {
  const event = stripe.webhooks.constructEvent(/* ... */);

  if (event.type === 'checkout.session.completed') {
    await sendWelcomeEmail(session.customer_email); // 3 seconds
    await createUserAccount(session);               // 2 seconds
    await provisionSubscriptionAccess(session);     // 4 seconds
    await notifySlack(session);                     // 2 seconds
    // Total: ~11 seconds — Stripe already marked this as failed
  }

  res.json({ received: true }); // Too late
});

The fix — acknowledge immediately, process asynchronously:

app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), async (req, res) => {
  const event = stripe.webhooks.constructEvent(
    req.body,
    req.headers['stripe-signature'],
    process.env.STRIPE_WEBHOOK_SECRET
  );

  // Respond immediately
  res.json({ received: true });

  // Process after response
  await queue.add('stripe-event', { event });
});

Use any queue — Bull, BullMQ, Inngest, Trigger.dev, or a simple background process. The webhook handler’s only job is to verify the signature, acknowledge receipt, and hand off to the queue.

5. You’re Trusting the Event Payload Instead of Re-fetching

Stripe’s docs are clear about this but it’s easy to miss: don’t trust the data in the webhook payload. Fetch the object from the Stripe API directly.

Why: webhooks can be delayed. The data in a webhook that arrives 30 seconds after the event may already be stale. A subscription might have been updated, a payment might have been refunded, a dispute might have been resolved.

// Wrong — trusts the payload directly
if (event.type === 'customer.subscription.updated') {
  const subscription = event.data.object;
  await updateUserSubscription(subscription.status); // Could be stale
}

// Right — re-fetch from Stripe
if (event.type === 'customer.subscription.updated') {
  const subscription = await stripe.subscriptions.retrieve(
    event.data.object.id
  );
  await updateUserSubscription(subscription.status); // Always current
}

This also protects against a subtle attack: a malicious actor constructing a fake event with manipulated data. Signature verification prevents this, but re-fetching adds defense in depth.

The Production Checklist

Before you ship your webhook handler:

[ ] Using raw request body (not parsed JSON) for signature verification
[ ] Production environment has the live mode signing secret
[ ] Idempotency implemented — event IDs stored and checked before processing
[ ] Handler responds within 10 seconds — heavy work in a queue
[ ] Re-fetching objects from the Stripe API instead of trusting payload data
[ ] Monitoring set up for failed deliveries in the Stripe Dashboard
[ ] Stripe’s webhook retry behavior tested with the Stripe CLI

Testing Without Deploying

The Stripe CLI makes local webhook testing trivial:

# Install
brew install stripe/stripe-cli/stripe

# Log in
stripe login

# Forward webhooks to your local server
stripe listen --forward-to localhost:3000/webhooks/stripe

# Trigger a test event
stripe trigger checkout.session.completed

The CLI prints the webhook signing secret it’s using — make sure your local STRIPE_WEBHOOK_SECRET matches it.

If you’re building on Stripe and hitting something not covered here — idempotency edge cases, handling events for connected accounts, testing in a CI pipeline — drop a comment below.

Disclosure: This post was produced by AXIOM, an agentic developer advocacy workflow powered by Anthropic’s Claude, operated by Jordan Sterchele. Human-reviewed before publication.

推荐订阅源

DEV Community