Handling payment confirmations safely: a checklist from Stripe's webhook and PaymentIntent documentation
Review Stripe webhook verification, durable event acceptance, duplicate handling and payment reconciliation before fulfilling an order.
When a customer pays on a website, the page the customer sees is not the only place the result shows up. The payment provider also tells your server. If your server trusts the wrong signal, you can ship an order that was never paid, or miss one that was. This article walks through what Stripe's own documentation says about that second signal, called a webhook. Everything here is Stripe's wording of Stripe's behaviour as read on 15 November 2026. Other providers work differently in the details, and you should read their pages. Use sandbox (test) keys while building.
Two pieces: a payment object and an event
Stripe's Payment Intents page says each PaymentIntent typically matches one shopping cart or customer session. It holds the amount, currency and supported payment methods, and its status changes through the payment. A client secret lets the browser finish the payment; Stripe says not to log it, put it in URLs or show it to anyone but the customer, and to use TLS on any page carrying it. After the browser confirms, Stripe's page says to have your server watch webhooks to find out whether the payment succeeded or failed.
Stripe's best practices on that page: create the PaymentIntent when you know the amount; reuse the same one if checkout is interrupted, so its history of failed attempts stays together; and send an idempotency key so a retry does not create a duplicate for the same purchase. It also says a PaymentIntent can have more than one Charge if there were several attempts. Before fulfillment, also reconcile the verified event/object with your expected order, account, amount, currency and payment state; a signed event alone does not prove that this particular order should ship. Metadata can hold your own order ID for reconciliation, but not sensitive data such as card details or personal information.
What a webhook endpoint must do
From the Webhooks page:
- Accept POST requests with a JSON body. The live endpoint must be a public HTTPS URL; Stripe supports TLS 1.2 and 1.3. For local work, Stripe suggests its command line tool forwarding events to localhost, or a tunnelling tool.
- Verify the signature. Stripe signs every event with a Stripe-Signature header. Stripe warns that without verification an attacker could send fake events to trigger actions such as fulfilling orders or granting access, and recommends using its official libraries. It also recommends allowing only Stripe's listed IP addresses, as a second protection beside the signature.
- Keep the raw body. Verification needs the exact body bytes. A framework that parses and re-serialises the body first will make verification fail.
- Check the timestamp. The signed timestamp protects against replay of a captured request. Stripe's libraries tolerate five minutes by default; Stripe says never set the tolerance to 0 since that turns off the recency check, and says to keep the server clock accurate.
- Return a 2xx quickly after verification and durable acceptance. Reliably store/enqueue the verified event before acknowledging it, so a crash after the response cannot silently lose fulfillment. If durable acceptance fails, return an appropriate failure so delivery can be retried. Do the slow work, such as marking an invoice paid in an accounting system, after replying. Stripe recommends handing events to an asynchronous queue so a spike (it gives month-start subscription renewals as an example) does not overwhelm the server.
- Handle duplicates. Stripe says the same event can arrive more than once. Log processed event IDs and skip repeats; in some cases two separate events are generated, and the page suggests comparing the object ID plus event type.
- Do not depend on order. Stripe does not guarantee events arrive in the order they were generated, and says not to use the created time to decide order. If an event arrives before the object it relates to, fetch the object through the API.
- Exempt the route from CSRF checks if your framework applies them to every POST, since Stripe's requests do not carry your site's token. Signature verification takes its place for this one route.
- Subscribe only to the events you need.
- Roll signing secrets periodically or if you suspect a leak. Stripe lets the old secret stay valid for up to 7 days during the change.
Retries and failure handling
Stripe says it retries failed deliveries for up to three days with exponential back-off in live mode, and three times over a few hours for events created in a sandbox. A redirect response counts as a failure. A manual resend is available in the dashboard for up to 15 days and by command line for up to 30 days; resending does not stop the automatic retries. The page's table of failure causes (cannot connect, 3xx, 4xx, 5xx, TLS error, timeout) is a useful starting point for debugging.
Testing
Stripe's testing page says test transactions in a sandbox do not move money, tests need test API keys, and real card details are not to be used, since Stripe says its services agreement prohibits live-mode testing with real payment method details. For test code it recommends test payment method tokens instead of raw card numbers so server code stays free of card data. It also says to use a different test card for each independent end-to-end scenario since card-level state carries over, and not to load-test in the sandbox because of rate limits. Before going live it says to swap in live keys and store them in a secrets vault or environment variables, not in source control. Omnistu's advice, not Stripe's: write the webhook tests for duplicates, out-of-order events and bad signatures as well as the success case.
Questions to ask your developer
- Which event tells the server the order is paid, and what happens if it arrives twice?
- Is the signature checked on the raw body, and can the tolerance be 0 anywhere?
- What does the endpoint do if the queue is slow or the database is down?
- Where are keys and signing secrets stored, and when were they last rolled?
- Is there a test for a forged event?
Limits
Source is one vendor's documentation; Stripe's page described features (thin and snapshot events, newer APIs) that we did not cover. We read only the first part of the testing page. Rules about handling card data, fraud, tax and refunds were not researched. Real payments need account setup and legal and compliance review that this article does not cover. No claims about conversion or fraud rates are made.
By Omnistu.