Retries, Idempotent Handling and the CLI

Design handlers for at-least-once delivery

If your endpoint does not return a 2xx quickly, Stripe retries the delivery with backoff, in live mode for up to three days, so the same event can arrive more than once. Events can also arrive out of order. Make processing idempotent: record each event.id you have processed (or make the fulfilment itself idempotent, for example by marking the order paid only once) and skip duplicates. Return 2xx fast and do slow work in a background job. When order matters, fetch the latest object state from the API instead of trusting the event payload alone. For local development, the Stripe CLI can forward events to your machine and trigger test events.

Forward and trigger events locally

Stripe CLI commands.

# authenticate the CLI with your account (test mode)
stripe login

# forward events to your local server; the CLI prints a whsec_... secret to use
stripe listen --forward-to localhost:4242/webhook

# in another terminal, fire test events
stripe trigger payment_intent.succeeded
stripe trigger checkout.session.completed

Store processed event IDs with a unique constraint

Insert the event ID into a table with a unique index inside the same transaction as the fulfilment. A duplicate delivery then fails the insert and is safely ignored.

त्वरित जाँच: Your handler receives the same event ID twice. What should it do?

• Return 500 so Stripe stops sending
• Fulfil the order a second time
• Recognise it as already processed and return 2xx without fulfilling again
• Delete the webhook endpoint