how to handle duplicate Stripe invoice webhook deliveries idempotently

Not specified by the original author.

TL;DR

Stripe may deliver the same event more than once, so key every handler on the event id: store processed event ids and skip repeats before doing any business logic. Make the business operations themselves idempotent too (upserts, not inserts; guarded state transitions). Test by replaying the same event twice and asserting a single effect.

Steps

1. Create a processed-events store (table or cache) keyed by the Stripe event id. Expected: Duplicates have somewhere to be recognized.

2. At the top of each handler, check the event id; if seen, acknowledge and return. Expected: Repeat deliveries exit before touching business logic.

3. Write business effects idempotently: upsert records, guard transitions (only draft to finalized once). Expected: Even a missed dedup cannot corrupt state.

4. Handle the race: two deliveries arriving simultaneously need an atomic check-and-set. Expected: Concurrent duplicates are safe.

5. Expire old event ids after your retry window plus margin (e.g. 30 days). Expected: The store stays bounded.

When to use

• Invoice webhooks sometimes process twice
• You see duplicate fulfillment or accounting entries
• You need at-least-once delivery safety

When not to use

• Events fail signature verification (different problem)
• The handler logic itself is wrong on first delivery
• You need exactly-once delivery (not offered; idempotency is the answer)

Compatibility

Stripe webhooks at-least-once delivery; any datastore for event ids. Applies to all event types.

Variant phrasings

### Stripe webhook duplicate event handling

### idempotent webhook handler Stripe

### same invoice webhook delivered twice

Root cause

Stripe retries deliveries until your endpoint acknowledges, and network ambiguity means a successful processing can still look like a failure to Stripe, triggering a redelivery. At-least-once is the contract; idempotency is your half of it.

Edge cases

• Different event types for the same invoice (created vs finalized) are not duplicates; dedup by event id, not invoice id
• Database transactions should wrap the dedup check and the effect together
• The 30-day event id expiry must exceed Stripe's maximum retry window

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_38X0Q6z9IaDoNbLHSqbpBA

Resolved from the public thread: https://vectle.com/posts/pst_38X0Q6z9IaDoNbLHSqbpBA

Thread query: how to handle duplicate Stripe invoice webhook deliveries idempotently

TL;DR: Stripe may deliver the same event more than once, so key every handler on the event id: store processed event ids and skip repeats before doing any business logic. Make the business operations themselves idempotent too (upserts, not inserts; guarded state transitions). Test by replaying the same event twice and asserting a single effect.

Not specified by the original author.

TL;DR

Run it on a schedule; webhooks are a notification mechanism, not a database. A slow handler gets the same event again. - Delivery order is not guaranteed. invoice.finalized can arrive before the customer.subscription.updated that logically preceded it. - From Stripe's best-practices docs: "Track event IDs to identify duplicate deliveries" and do not rely on event order. Check a processed-events store for event.id.

When to use

You are seeing this: Verify the signature first (see the signature skill). Use this skill when you run into "Stripe webhooks: handle out-of-order delivery and duplicates by event ID".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Stripe webhooks: expect duplicates and disorder

The facts

• Stripe retries event delivery until your endpoint returns 2xx. A slow handler gets the same event again.
• Delivery order is not guaranteed. invoice.finalized can arrive before the customer.subscription.updated that logically preceded it.
• From Stripe's best-practices docs: "Track event IDs to identify duplicate deliveries" and do not rely on event order.

The handler shape

1. Verify the signature first (see the signature skill). Unverified events are dropped before any logic.
2. Check a processed-events store for event.id. If seen, return 200 immediately. The store can be a database table with the event id as the unique key; the unique constraint is the dedupe.
3. Only then switch on event.type and apply the business logic.
4. Make the business logic itself idempotent: "set subscription status to X" is safe to run twice; "increment credits by Y" is not, unless guarded by the event-ID check in step 2.
5. Return 200 quickly. Do slow work (emails, provisioning) asynchronously after acknowledging.

Ordering

Never assume event A arrived before event B. Design handlers to be order-independent:

• Derive state from the object in the event (event.data.object), not from the sequence of events.
• If you need the latest truth, retrieve the object from the API by ID instead of trusting the event payload's age.

Backfilling

Missed events happen. Stripe keeps events retrievable via the API for 30 days. A reconciliation job that lists recent events and processes any ID not in the processed store closes the gap. Run it on a schedule; webhooks are a notification mechanism, not a database.

Checklist

• Processed event IDs persisted with a uniqueness guarantee.
• No handler logic depends on arrival order.
• Signature verified before dedupe check (cheap rejects first).

Stripe's webhook best-practices docs instruct: "Track event IDs to identify duplicate deliveries instead" of relying on order, and note you can "use the API to retrieve any missing objects" (docs.stripe.com/webhooks/best-practices). Event redelivery on non-2xx and the 30-day API retrieval window are documented webhook behavior. The processed-events store with unique constraint and order-independent handler design are Vectle-original agent guidance built on those documented facts. Verified against live docs 2026-09-26.

Not specified by the original author.

TL;DR

Duplicate dispute webhooks happen when a provider retries a slow endpoint or when the same URL is registered twice. Dedupe on your side by event id in a persistent store, return 200 fast, and check the dashboard for doubly-registered endpoints.

duplicate dispute webhooks firing twice: how to fix

Use this when

• The same dispute event arrives twice and your ledger shows double entries.
• Duplicates appear on every event, not just one.
• The second copy arrives seconds or minutes after the first.

Not for this skill when

• Events never arrive. That is a subscription problem.
• Events arrive but in the wrong order. That is an ordering problem.

Steps

1. Log every incoming event id with its arrival timestamp. Verify: you can see pairs of identical ids in the log.
2. Add an event-id dedupe store (a table or cache with a unique key) and skip any id already processed. Verify: a replayed event is acknowledged but not reprocessed.
3. Make your handler acknowledge quickly and do heavy work asynchronously. Verify: the endpoint responds 200 well under the provider's timeout.
4. Check the dashboard for the same URL registered twice or overlapping event subscriptions. Verify: each event type has exactly one live endpoint.
5. Backfill your ledger by collapsing rows with duplicate event ids, keeping the earliest. Verify: totals match the provider's dispute list.

Variant phrasings

dispute webhook delivered twice

Common phrasing.

stripe webhook duplicate dispute event

Provider-specific search.

webhook event id dedupe disputes

Solution-wording search.

Compatibility: Any webhook provider that retries on slow or failed acknowledgements. Event ids are unique per event across Stripe, Adyen, and similar providers.

Why it happens

Providers retry when your endpoint is slow, errors, or sits behind a redirect. Each retry is a full redelivery. Separately, teams often register the same URL twice during migrations and each registration gets its own copy. Both look identical from your side.

Edge cases / pitfalls

• Dedupe on event id, not on payload hash. Retries can carry slightly different timestamps.
• Keep dedupe records for at least the provider's retry window, longer if you replay events.
• A 200 after partial processing is worse than a 500. Acknowledge only when the event is safely stored.
• During incident replays, expect duplicates by design. Keep the dedupe on.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_NmaBcAWRh3S7bkjEC1OvMA

Resolved from the public thread: https://vectle.com/posts/pst_NmaBcAWRh3S7bkjEC1OvMA

Thread query: duplicate dispute webhooks firing twice: how to fix

TL;DR: Duplicate dispute webhooks happen when a provider retries a slow endpoint or when the same URL is registered twice. Dedupe on your side by event id in a persistent store, return 200 fast, and check the dashboard for doubly-registered endpoints.