Concurrent duplicate Stripe webhook deliveries crash instead of no-oping

Nobody has started this yet — be first.

Business impact

Stripe explicitly documents that webhook delivery is at-least-once, not exactly-once -- it retries on timeouts and non-2xx responses, and it can also, rarely, deliver the same event twice close together under completely normal operation. This project's answer to that is ProcessedWebhookEvent.stripe_event_id being unique plus a "have we seen this already?" check. That check has a race window: two near-simultaneous deliveries of the same event can both pass the "not seen yet" check before either has committed, and the loser of that race now hits a database uniqueness violation with nothing catching it -- an unhandled exception, a 500 back to Stripe, and a retry storm that keeps happening every time delivery happens to overlap like this.

Problem

process_event checks whether an event id has already been processed and, later, separately commits the new ProcessedWebhookEvent row, with no locking between the two round-trips -- and nothing catches the unique-constraint violation when two concurrent deliveries both pass the check.

Current behavior

The already = ProcessedWebhookEvent.query.filter_by(stripe_event_id=event_id).first() check and the later db.session.commit() are two separate round-trips; if two concurrent transactions both run the SELECT before either has committed its INSERT, both see "not seen yet" and both proceed -- one succeeds, and the other's commit() raises an uncaught IntegrityError from the unique constraint on stripe_event_id.

Expected behavior

When two deliveries of the identical event race like this, exactly one succeeds cleanly ("processed"), and the other resolves as "already_processed" (or an equivalent success outcome) -- not an unhandled exception, not a 500. Exactly one ProcessedWebhookEvent row ends up persisted, and the event's effect (e.g. a subscription activation) is applied exactly once regardless of which request won.

Steps to reproduce

Force two threads to call process_event() with the identical event id, synchronized with a threading.Barrier plus a small artificial delay between the check and the commit so both checks run before either commit lands.
Observe: one call succeeds, the other raises an uncaught IntegrityError instead of resolving as already_processed.

Why this matters

This is a textbook check-then-act (TOCTOU) race, and the fix is not "check harder" -- no amount of re-reading the SELECT closes the window between two independent connections. The database's own unique constraint is already the real safety net here (that is why stripe_event_id is unique=True on the model); what is missing is handling the constraint violation as the expected, benign outcome it is, rather than letting it propagate as an unhandled error.

Suggested approach

Wrap db.session.commit() in a try/except for exactly this constraint violation, treat it as "someone else already recorded this event id," roll back the session, and return the same "already_processed" outcome the pre-check path returns. sqlalchemy.exc has the relevant exception type.

Acceptance criteria

Two concurrent deliveries of the identical event never produce an unhandled exception or a 500
Exactly one ProcessedWebhookEvent row exists afterward
The event's effect (subscription activation, in the test) is applied exactly once, regardless of which concurrent call won
Sequential replay (the simple case, already covered by the project's own suite) still works

Verification

pytest practice_tickets/tests/test_ticket_13_webhook_idempotency_race.py -v

Hints (0/2)

Try it without hints first — the reading is the exercise.

Working on this ticket

Work on a branch named for the ticket — that's what you'll submit.

Branch off your fork

$git checkout -b fix/webhook-idempotency-race

Fix it and commit

Meet every acceptance criterion, and add a test that would have caught this.

Push the branch

$git push -u origin fix/webhook-idempotency-race

Submit it below

Paste your fork URL and the branch name, with a short write-up of the root cause.

Submit your fix

Questions

Stuck on something?

Ask about anything unclear in the ticket — the maintainer and anyone who has solved it can answer. Please don't post full solutions.

No questions yet. If something in this ticket reads ambiguously, you are probably not the only one — ask.

The project

Multi-Tenant SaaS Starter

A Flask multi-tenant SaaS reference app where Postgres Row-Level Security -- not an app-level `WHERE tenant_id = ...` -- is the actual isolation boundary, plus subdomain tenant resolution, per-tenant RBAC, an append-only audit trail, and idempotent Stripe subscription billing.

Fork on GitHub

Download

Setup

Multi-Tenant SaaS Starter

git clone <your-fork>
cd FlaskDevTraining/saas_starter
docker compose up --build   # Postgres + Redis + the Flask dev server (auto-reload)

Migrations (including the RLS policies) run automatically on boot. Then seed two demo tenants -- (active subscription) and (still on trial):