Webhook Replay

Stripe delivers webhooks at least once , not exactly once. Any handler for checkout.session.completed, invoice.paid, etc. can receive the same event twice (redelivery after a timeout, a retried delivery after your endpoint 500s, manual replay from the Stripe dashboard). A handler that isn't idempotent will double-grant credits, double-send receipt emails, or re-fire jobs on every replay.

There are two separate problems here, and they need two separate guards:

The DB write must not double-apply. Granting credits or upserting a subscription twice corrupts state.
Side effects that aren't naturally idempotent (sending an email, enqueuing a one-time job) must not re-fire on a replay even if the underlying write is safe to repeat.

The rule

Dedup the write with a marker row checked and inserted in the same transaction as the mutation. Gate side effects with a granted/isReplay flag computed from a fresh read inside that same transaction, so emits/emails only fire on the first delivery.

make check-webhook-idempotency enforces (at file-presence level) that src/features/billing/server/stripe-*.server.ts still contains both patterns , see the Makefile target for what it does and doesn't catch.

Note: the callback must be async, with real awaits inside , not synchronous. This repo's db.transaction() runs on drizzle-orm/node-postgres, a real Postgres connection doing network I/O over a pooled connection, not Bun's native synchronous SQLite wrapper. See CLAUDE.md's "Shared-DB Transactions Must Use Async Callbacks (reversed from base warpkit)" section , that title is not a typo, this rule is the opposite of the base template's. A sync callback (.sync()/.run(), no await) does not compile against this driver, and if you're porting a sync example from somewhere else, adapting it to await mechanically without also awaiting the whole db.transaction(...) call is a correctness bug, not just a style issue: the transaction can commit before the callback's writes actually land.

Right: dedup marker in the same transaction as the write

handleCreditsPurchase in src/features/billing/server/stripe-checkout.server.ts dedups on the Stripe payment intent ID. The marker insert and the credit increment happen inside the same db.transaction, so a crash between the two can't strand a marker without the grant (or vice versa):

let granted = false;
await db.transaction(async tx => {
  const existing = await tx.query.purchases.findFirst({
    where: eq(purchases.stripePaymentIntentId, paymentIntentId)
  });
  if (existing) return; // already granted, replay , no-op

  await tx.insert(purchases).values({ /* marker row */ });

  await tx
    .update(users)
    .set({ credits: sql`credits + ${amount}`, updatedAt: new Date() })
    .where(eq(users.id, userId));
  granted = true;
});

if (granted) {
  invalidateBootstrapCache(userId);
  await emit('credits.purchased', { userId, amount });
}

The emit only fires when granted is true , a replay short-circuits before it, so it can't be sent twice either. Note the outer await db.transaction(...) , the whole transaction is awaited before the if (granted) check runs, so the write is guaranteed committed (or rolled back on throw) before any side effect fires.

Right: isReplay flag for upserts where the write is naturally idempotent

handleSubscriptionCheckout (same file) upserts the subscription row with onConflictDoUpdate , the write itself is safe to repeat. But the subscription.activated emit (receipt email, trial-expiring job) must only fire once. The handler computes isReplay from a fresh read inside the transaction, before the upsert:

let isReplay = false;

await db.transaction(async tx => {
  if (subId) {
    const existingSub = await tx.query.subscriptions.findFirst({
      where: eq(subscriptions.userId, userId),
      columns: { stripeSubscriptionId: true }
    });
    isReplay = existingSub?.stripeSubscriptionId === subId;
  }

  await tx
    .insert(subscriptions)
    .values({ /* ... */ })
    .onConflictDoUpdate({ /* ... */ });
});

invalidateSubscriptionCache(userId);
invalidateBootstrapCache(userId);

if (userEmail && !isReplay) {
  await emit('subscription.activated', { /* ... */ });
}

Wrong: check-then-write outside the transaction

// WRONG , dedup read and write are not atomic; two concurrent redeliveries
// can both pass the findFirst check before either insert commits
const existing = await db.query.purchases.findFirst({
  where: eq(purchases.stripePaymentIntentId, paymentIntentId)
});
if (existing) return;

await db.insert(purchases).values({ /* marker row */ });
await db.update(users).set({ credits: sql`credits + ${amount}` });

Two redeliveries arriving close together can both read "no existing marker" before either write commits , the dedup check itself has a TOCTOU race unless it's inside the same transaction as the write it's guarding. See gate-ordering.md for the general version of this rule , note that doc also uses withUserTransaction now, not the old per-user lock.

Wrong: synchronous-style callback (does not compile on this driver)

// WRONG , .sync()/.run() are bun:sqlite-only APIs; drizzle-orm/node-postgres
// has no synchronous query methods, this throws a type error
db.transaction(tx => {
  const existing = tx.query.purchases
    .findFirst({ where: eq(purchases.stripePaymentIntentId, paymentIntentId) })
    .sync();
  if (existing) return;
  tx.insert(purchases).values({ /* marker row */ }).run();
});

If you're used to the base warpkit template's SQLite version of this doc, this is the one rule that inverted during the Postgres port , don't carry the sync-callback habit over.

Adding a new webhook handler

Identify what must not double-apply (a DB write) vs what must not double-fire (an emit, an email, a job enqueue).
Dedup the write with a marker row (or a naturally-idempotent upsert) inside an await db.transaction(async tx => { ... }), with real awaits on every tx call inside.
If any side effect isn't safe to repeat, compute a granted/isReplay flag from a fresh read inside that same transaction and gate the side effect on it, after the transaction has been awaited.
Run make check-webhook-idempotency to confirm the new handler file still contains both required patterns (file-presence level , see the Makefile target for what it does and doesn't catch).
Reference implementation: handleCreditsPurchase and handleSubscriptionCheckout in src/features/billing/server/stripe-checkout.server.ts.