The Stripe Webhook Event Cheatsheet

Stripe has an amazing set of webhooks for your application to listen for. Every event that happens on your Stripe account (or an account your application is connected to) blasts events to your webhook receiver.

"But", you ask, "what events fire when?" Below you'll find some common scenarios and the events that Stripe will fire at your webhook receiver in response. Clicking on any event name will show a full example webhook. You can find full descriptions for these events in Stripe's awesome documentation . For more background information on how Stripe processes a charge check out The Life of a Stripe Charge and my book Mastering Modern Payments: Using Stripe with Rails .

Mastering Modern Payments

Get a free five-part email course on how to use Stripe with Ruby on Rails. Includes tips on testing, responding to webhooks, async payments, and more. Includes three free chapters of Mastering Modern Payments.

We won't send you spam. Unsubscribe at any time.

Simple One-off Purchases with Charges

1. Customer successfully purchases a single one-off item

The simplest possible starting point. A single one-off purchase.

2. Customer's card is declined

This event also describes other failure modes, like an invalid expiration date or a failed CVC check if you have the option turned on to decline on a failed check.

3. Customer successfully purchases and then requests a refund

Typically you'll hit the refund button in Stripe's management interface to generate a refunded event.

4. Create a charge without capturing it, capture later

Normally charges are authorized (check with the bank for available funds) and captured (actually request a fund transfer) at the same time. Stripe allows you to separate the two events. For example, if you're shipping goods that have a few days of lead time you'd want to authorize the charge up front but only capture it when you actually ship.

5. Charge then modify description

After making a charge you can update the `description` and `metadata` fields to add or alter application-specific information.

Disputes

6. Customer disputes a charge, you upload evidence

Disputes happen. It's just a fact when you're charging people money. Stripe will of course send your application a series of webhooks as the dispute process plays out.

Customers

7. Create customer and charge them immediately

This is the same flow as a simple charge with the added benefit of being able to charge the customer again later.

8. Create a customer with a plan without a trial

Customer and subscriptions are where Stripe's webhook system really starts to shine. All of these events happen more or less simultaneously when you create a customer object and include the plan_id and card attributes.

9. Create a customer with a plan with a trial

Trials let you give a customer a taste of your application before charging them. Stripe will create a $0 invoice and "pay" it when you create the subscription, and then later will send you a customer.subscription.trial_will_end three days before creating the first real invoice.

10. Create a customer with a plan with a discount, no trial

Discounted subscriptions are essentially the same as a normal subscription with one more event, `customer.discount.created`.

11. Invoice charge attempt succeeds

The normal course of events with a subscription is that the invoice is paid properly and on time. Stripe will send an `invoice.created` event one hour before attempting to pay the invoice, which gives you time to add items to the invoice for balance billing or utility-style billing purposes.

12. Invoice charge attempt fails

When you run a subscription service eventually you'll have customers who cancel their card without telling you. When that happens Stripe will send you a series of events. The key event is invoice.payment_failed, the rest just update various attributes on the corresponding Subscription and Customer. Stripe will attempt payment three times. After the third failed attempt the customer.subscription.updated event will be replaced with a customer.subscription.deleted event.

13. Existing customer, adding invoice items

Adding invoice items for a customer without specifying an invoice will automatically add them to the next month's invoice. Pretty handy for doing usage billing, since you can just roll up the customer's daily usage and build an invoice item for every day.

14. Customer modifies existing card

Stripe's Card API lets you update some details about a card without fully adding a new one. For example, a customer's address changes or they get a new expiration date.

15. Customer changes to a different card

Of course if a customer wants to change their card entirely they have that option. This is the set of events that happens when you assign to the customer's `card` attribute. The sequence of events is essentially the same if you add a card and change their default card manually, just without the delete event.