← Back to Fixes
Stripe Webhook Idempotency in Postgres: Problem to Fix Production Guide
Implement retry-safe Stripe webhook processing with event ID deduplication and transactional updates.
Tweetable Insight#
Stripe retries are expected behavior; duplicates are your responsibility.
One-Sentence Definition#
Webhook idempotency ensures each billing event mutates your system once, even across retries.
Production Risk Warning#
Without idempotency, retries can create duplicate subscriptions and entitlements.
Problem (Search Intent First)#
Subscription rows duplicate after webhook retries or timeouts.
Why It Happens#
The API handler updates business tables without persisting processed event IDs.
Production-Grade Fix#
Track event.id with a unique constraint and short-circuit repeats.
Copy-Paste Solution#
sql
create table if not exists billing_webhook_events (
event_id text primary key,
received_at timestamptz not null default now()
);
Edge Cases#
- Out-of-order events still require state guards.
- Retries across regions require globally consistent event storage.