A research report on how Stripe uses webhooks to reliably confirm payments across Checkout and Invoices — the events, the lifecycle, the security rules, and how it applies to my SpinDry product page.
TL;DR — A redirect to a success page can be closed, refreshed, or faked, so it must never be your source of truth for “paid.” A webhook is Stripe calling your server directly to say what really happened. For one-time Checkout, listen for checkout.session.completed; for Invoices (and subscriptions), listen for invoice.paid. Always verify the signature, process each event once (idempotency), and reply 2xx within 20 seconds.
When a customer pays, Stripe sends them back to your success_url. That redirect is fine for showing a “thank you” message, but it is not reliable proof of payment: the customer might close the tab before it loads, lose their connection, or open the URL manually without paying. Payment methods that settle later (bank debits, some wallets) aren’t even “paid” yet at redirect time.
A webhook solves this. It’s an HTTP POST that Stripe sends from its servers directly to a URL on your server whenever something happens (a payment succeeds, an invoice is paid, a charge is refunded). It arrives regardless of what the customer’s browser does, and Stripe retries it until your server confirms receipt. That makes webhooks the trustworthy backbone for fulfilment, receipts, and evidence.
Mental model: the redirect is what the customer sees; the webhook is what your system trusts.
Stripe Checkout (both the hosted page and Payment Links) emits webhook events for the Checkout Session. The main one is checkout.session.completed, fired when the customer finishes the session. For card payments this effectively means paid; for delayed methods, payment may still be processing.
| Event | When it fires |
|---|---|
checkout.session.completed | Customer completed the session (start fulfilment here). |
checkout.session.async_payment_succeeded | A delayed payment method later succeeded. |
checkout.session.async_payment_failed | A delayed payment method later failed. |
checkout.session.expired | The session expired without payment. |
line_items expanded and check payment_status before fulfilling, rather than trusting the event body blindly.# SECRET keys live here on the SERVER only — never in a webpage. import stripe, os endpoint_secret = os.environ["STRIPE_WEBHOOK_SECRET"] # whsec_... @app.post("/webhook") def webhook(): payload = request.get_data() # RAW body, unmodified sig = request.headers["Stripe-Signature"] event = stripe.Webhook.construct_event(payload, sig, endpoint_secret) # verifies if event["type"] == "checkout.session.completed": session = event["data"]["object"] if already_processed(event["id"]): # idempotency return "", 200 fulfil_order(session) # mark paid, record evidence mark_processed(event["id"]) return "", 200 # 2xx tells Stripe "got it"
An invoice is a billing document with its own life. Instead of watching one “paid?” flag, you listen to events as it moves through states:
Invoices are created as draft; finalizing them makes them open (ready to pay). With automatic collection, Stripe finalizes and attempts payment for you. On success the status becomes paid.
| Event | When it fires |
|---|---|
invoice.created | A draft invoice was created. |
invoice.finalized | Draft became an open invoice, ready to be paid. |
invoice.paid | Recommended. Fires when paid or marked paid out-of-band. |
invoice.payment_succeeded | A payment attempt succeeded (not sent for out-of-band). |
invoice.payment_failed | A payment attempt failed (dunning / retry). |
invoice.voided | The invoice was cancelled. |
The one nuance to remember: invoice.paid covers both online payments and invoices marked paid manually (out-of-band), while invoice.payment_succeeded only fires for actual payment attempts. Stripe recommends listening to invoice.paid so you never miss a paid invoice.
Checkout and Invoices are two ways money arrives; webhooks are the single reliable channel that tells you it did. How they relate:
checkout.session.completed.invoice.paid.invoice.paid.So: one-time sale → Checkout events; recurring or billed sale → Invoice events; and in every case the webhook is what flips your own record to “paid” and writes the evidence.
checkout.session.completed, invoice.paid).whsec_… per endpoint. Test and live have different secrets.Stripe-Signature header + your signing secret. If a framework rewrites the body, verification fails.event.id and skip ones you’ve already handled, so retries don’t double-fulfil.2xx within 20 s; Stripe retries failures with backoff.stripe listen --forward-to …) replays real test events to your machine.Security boundary (same rule as Day 1): the secret key (sk_…) and the webhook signing secret (whsec_…) live in server environment variables only — never in a webpage, never in a public repo. My current SpinDry page uses a Payment Link, so it holds no keys at all.
SpinDry uses a Payment Link (Path A): my own Stripe account, no server, no keys — Stripe hosts everything and I can see test payments in my Dashboard. That sells, but the page alone never learns that a payment happened.
So I built Path B — and it is now live. My own Cloudflare Worker at spindry-webhook.nbybrandon.workers.dev receives every event, verifies the Stripe signature (HMAC-SHA256 via Web Crypto), and returns 200 — confirmed “Delivered” in the Stripe dashboard for checkout.session.completed. It records the event and can forward it to another URL, so a payment automatically triggers action elsewhere. That closes the loop for real: capability → product → payment → webhook → evidence.
Next from here: auto-write the JSONL evidence straight back to my runtime, and add coupons / subscription invoices.