Stripe webhook events: what each one means and what to email

Which one to use

Stripe sends a lot of events for one payment, and the one to trust depends on what you want to say.

• Somebody paid for the first time: checkout.session.completed if you use Checkout, and invoice.paid for anything billed as a subscription.
• A one-time payment you take with a PaymentIntent of your own: payment_intent.succeeded.
• A trial or a subscription began: customer.subscription.created.
• A subscription renewed: invoice.paid, with billing_reason set to subscription_cycle.
• A card failed: invoice.payment_failed.
• A trial is about to end: customer.subscription.trial_will_end.
• Somebody changed plan: customer.subscription.updated, read against previous_attributes.
• Somebody cancelled: customer.subscription.deleted, once the subscription has really ended.
• Somebody left checkout: checkout.session.expired.
• A refund was made: charge.refunded.

A first subscription payment sends several of these at once, so pick one for each email you send. The ones about customers, customer.created and customer.updated, are for knowing who somebody is and not for writing to them.

Handling any of them

Every event reaches your endpoint the same way, and Stripe's rules for it are the same for all twelve.

• Check the signature on every request, using the raw body of the request untouched.
• Return a 2xx before you do any slow work, such as sending the email.
• Keep the ids of the events you have handled. The same event can be delivered more than once, and sometimes two separate events describe the same thing.
• Do not rely on order. Stripe does not promise to deliver events in the order they happened.
• If your endpoint does not answer well, Stripe keeps retrying in live mode for up to three days.
• The shape of the payload follows the API version in use when the event happened. Version 2025-03-31.basil moved a subscription's billing period onto its items and removed the subscription field from invoices, so check which version your endpoint receives.

Stripe's own pages for these rules are Receive Stripe events in your webhook endpoint and Using webhooks with subscriptions, and the two changes to the API are in its changelog: invoices now say how they were generated and billing periods moved onto subscription items. Each event's page links the Stripe pages it was checked against.

With Kicklace

Connect Stripe under Settings → Connections → Stripe with one restricted key, and Kicklace adds its own webhook to your Stripe account and listens for exactly these twelve events, on a fixed API version, so what it receives does not change when your account's version does. Each one lands on the right person on your Lifecycle map, so what a customer did in Stripe sits beside what they did in your product, and a side road can start from a failed payment, a trial ending, a refund or a cancellation. Payments from Stripe lists what each one becomes.

Kicklace only reads Stripe. It never charges anybody and never changes a customer, a price or a payment. Nothing sends until you switch a sequence on. You can see the map on your own site in the demo, with no sign-up.