Back to blog
October 28, 2026·6 min read

Handling Stripe Webhooks Safely in Node.js: Signatures, Idempotency & Reconciliation

Payments
Stripe
NestJS
Backend

Wiring up Stripe Checkout takes an afternoon. Making sure your billing database stays accurate when a user refreshes the tab, a webhook is delivered three times, or an invoice event arrives before the checkout event is where real payment engineering starts.

Verify signatures against the raw body

The most common NestJS webhook bug happens before your handler even runs: JSON body parsing mutates whitespace or key ordering, causing stripe.webhooks.constructEvent to fail signature verification. Always enable rawBody on your NestJS application and pass the untouched Buffer to Stripe.

typescript@Post('webhooks/stripe')
async handleStripeWebhook(
  @Req() req: RawBodyRequest<Request>,
  @Headers('stripe-signature') sig: string,
) {
  const event = this.stripe.webhooks.constructEvent(
    req.rawBody!,
    sig,
    this.config.getOrThrow('STRIPE_WEBHOOK_SECRET'),
  );

  await this.billingQueue.add('stripe-event', { eventId: event.id, type: event.type, data: event.data.object });
  return { received: true };
}

Challenge

Acknowledge fast, process asynchronously

Stripe expects a 2xx response within a few seconds. Never run heavy database migrations, PDF invoice generation, or third-party email calls inline inside the webhook HTTP handler — push the verified event to a queue and return 200 immediately.

Idempotency by event ID

Stripe guarantees at-least-once delivery, not exactly-once. If your worker times out or Stripe retries, the same event.id will hit your processor again. Store processed event IDs in a unique-indexed table inside the same database transaction that updates the subscription or ledger.

typescriptawait this.db.transaction(async (tx) => {
  const inserted = await tx
    .insert(processedStripeEvents)
    .values({ eventId: event.id, type: event.type })
    .onConflictDoNothing()
    .returning();

  if (inserted.length === 0) {
    return; // Already processed — safe no-op
  }

  await this.applyBillingStateChange(tx, event);
});

Handle out-of-order events and reconcile

Result

Boring billing is good billing

With raw-body signature verification, fast queue handoff, transactional idempotency and nightly reconciliation, payment state stays consistent across network blips and deploy restarts.

Takeaways

Building a SaaS subscription engine or multi-currency billing flow? Explore our Payment & Fintech Systems services, see how we built Canadian invoicing in SoloBook, or contact us to review your architecture.


Working on something like this?

I build NestJS backends and AI integrations for SaaS, fintech and crypto products. Happy to talk through your architecture.

Get in touch →