Stripe Webhook Idempotency Pattern: One-Page Guide

Tweetable Definition#

Webhook reliability equals signature verification plus idempotency plus transactional updates.

Production Risk Warning#

Ignoring retries creates duplicate subscriptions and access drift.

Copy-Ready Snippet#

create table if not exists billing_webhook_events (
  event_id text primary key,
  received_at timestamptz not null default now()
);

One-Page Pattern#

1. Verify signature from raw body.
2. Start transaction.
3. Insert event_id into idempotency table.
4. If conflict: stop and return success.
5. Apply billing state mutation.
6. Commit and log outcome.

Common Pitfall#

Never treat webhook retries as errors; treat them as a normal delivery guarantee.

Related Incidents#

• INC-006
• INC-007
• Stripe Webhooks vs Polling in Production: Reliability Comparison Guide
• How to Set Up Idempotency Key in Next.js (Step by Step)
• Next.js & Supabase Stripe Subscriptions: The Complete SaaS Guide
• Stripe Webhook Signature Verification Failed in Next.js

Related Assets#

• Stripe Webhook Citation Pack