What you learn
- What webhooks are, why polling is the wrong instinct, and how to verify webhook signatures
- Idempotency, proration on mid-cycle upgrades, and coupons versus promotion codes
- Embedded checkout and the webhook gotchas that catch every beginner
Summary
In Part 1 you took a payment. But here is the uncomfortable truth: after redirecting a customer to Checkout, your app does not actually know what happened to them. Did they pay? Did the card fail later? Did they cancel next month? Guessing is how people accidentally give away the product for free or keep charging cancelled customers. The answer is webhooks: Stripe calls your app whenever something happens, so your app reacts to reality instead of guessing. This lesson makes your billing trustworthy: verified webhooks, idempotency, proration, coupons, embedded checkout, and the gotchas that bite everyone the first time.
What you will learn
You will learn what a webhook is and why polling Stripe is the wrong instinct, how to verify a webhook signature so attackers cannot fake events, how idempotency stops you double-processing a duplicated event, how proration fairly handles a mid-cycle plan change, the difference between coupons and promotion codes, how embedded checkout works, and the webhook gotchas that cause the classic "it worked in test but broke in production" failure.
Prerequisites
Stripe Part 1 and a working subscription Checkout, plus a backend that can receive HTTP requests (your Convex actions or your framework's server routes), because a webhook is just Stripe sending a request to your backend. The secrets lesson, too, since the webhook signing secret is one more key to guard.
An API is a way for two programs to talk to each other. Learn what an API is, how it works, and why it matters for building with AI.
A .env file stores secrets like API keys outside your code so they never get published. Learn what it is, how it works and how to keep it safe.
JSON, YAML and Markdown are three plain-text formats you will meet constantly. Learn what each is for and how to read them at a glance.
The problem
The naive instinct after Checkout is to poll: every few seconds, ask Stripe "did they pay yet?" This is wrong on every axis. It wastes requests, it is slow, it misses events that happen later (a renewal next month, a card that fails in 30 days, a cancellation), and it does not scale. Worse, relying on the success-URL redirect alone is unreliable - a customer can pay and then close the tab before the redirect fires, and now they paid but your app never recorded it. The right model is the reverse: do not ask, be told. Stripe pushes an event to your backend the instant something happens, and your app reacts. That is a webhook, and getting it right is what makes billing trustworthy.
Comments
Loading comments.
Post a comment