Skip to content
ADVISORY RECONCILIATION · STRIPE ↔ ENTITLEMENTSRun the browser-only CSV audit

Problem

Stripe webhook failures and duplicate events

Webhooks are the backbone of subscription state synchronization. When they fail, duplicate, or arrive out of order, your application's access state drifts from Stripe's billing state.

Common webhook failure modes

  • Endpoint downtime: Your webhook endpoint was down when Stripe sent the event. Stripe retries, but retries have limits.
  • Timeout: Your endpoint took too long to respond (Stripe expects a 2xx within 20 seconds).
  • Signature verification failure: The webhook signature check failed, possibly due to a rotated secret or clock skew.
  • Unhandled event type: Your code doesn't handle a specific event type, so it's silently ignored.
  • Database write failure: The webhook was received but the database update failed, leaving state inconsistent.

Duplicate and replayed events

Stripe guarantees at-least-once delivery. This means your webhook endpoint may receive the same event multiple times. Without idempotency, this can cause:

  • Duplicate access grants or revocations.
  • Double-counting in analytics or billing.
  • Race conditions when events arrive out of order.

Idempotency pattern

  1. Store the event ID (evt_...) in a deduplication table.
  2. Before processing, check if the event ID was already processed.
  3. If yes, return 200 immediately without reprocessing.
  4. If no, process the event and record the event ID atomically.
  5. Use a unique constraint on the event ID to prevent race conditions.

How SubSync Guard helps

SubSync Guard does not rely on webhooks for its reconciliation. It pulls the current state from Stripe's API on a schedule and compares it with your application's entitlement snapshots. This catches mismatches regardless of whether webhooks were delivered, duplicated, or dropped.

The Supabase integration uses signed event ingestion with HMAC verification, nonce validation, and replay protection — demonstrating the pattern for secure webhook-like event processing.

Recommended fix steps

  1. Implement webhook signature verification using Stripe's official library.
  2. Add idempotency with a deduplication table and unique constraint on event ID.
  3. Return 200 immediately after receiving the event, process asynchronously.
  4. Log all received events for debugging and audit.
  5. Add a reconciliation job as a safety net for missed webhooks.
  6. Monitor webhook delivery in Stripe Dashboard → Developers → Webhooks.

Authoritative sources