Handling Stripe Webhooks Safely in Node.js: Signatures, Idempotency & Reconciliation
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
- Do not rely solely on incremental deltas — fetch the latest Subscription or Invoice object from Stripe when state transitions conflict.
- Compare event timestamps or Stripe object versions so an older retried event never overwrites a newer cancellation or upgrade.
- Run a scheduled reconciliation job every night for active subscriptions created or updated in the last 24 hours to catch any dropped events.
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
- Verify stripe-signature using the exact raw Request Buffer, never re-serialized JSON.
- Return 200 right after enqueueing; do business work in a background worker.
- Enforce idempotency at the database layer using a unique constraint on event.id.
- Pair webhook listeners with a scheduled reconciliation job for 100% state accuracy.
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 →