Using Stripe Webhooks

Listening for Stripe webhooks

Overview

In order to keep your database in sync with Stripe subscription events, we need to listen to Stripe webhooks. When free trials end, cancellations, upgrades, and downgrades come through you will be notified and change the user status in your system. This allows to you restrict access, change functionality, or provide notifications to the users, whether the changes are made by the user from the Customer Portal, or by an Admin from the Stripe Dashboard. Here's what we'll go over:

Events needed. Stripe provides tons of events, but we only need to listen to some to complete our billing flow.

If you are using a platform plugin, this step could be different for you. Make sure to check out the integrations for specific instructions.

Events needed

Here's a list of our recommended events to listen to. Read here for a full list of Stripe available events, and here for more information on implementing Stripe webhook listener on your app.

Necessary

Event Name	Description
customer.subscription.created	Occurs whenever a customer is signed up for a new plan. Use it to ensure the data was populated in your user system by the handleResponse method.
customer.subscription.deleted	Occurs whenever a customer's subscription ends. Use this to update the user's subscription status.
customer.subscription.updated	Occurs whenever a subscription changes (e.g., switching from one plan to another, or changing the status from trial to active). Use this to update the user's subscription status for upgrades/downgrades and trial ends.

Nice to haves

Event Name	Description
customer.source.created	Occurs whenever a new source is created for a customer. Use for sending notifications to your user.
customer.source.expiring	Occurs whenever a card or source will expire at the end of the month. Use for sending notifications to your user.
customer.source.updated	Occurs whenever a source's details are changed. Use for sending notifications to your user.
customer.subscription.trial_will_end	Occurs three days before a subscription's trial period is scheduled to end, or when a trial is ended immediately (using trial_end=now). If you have a free trial, use for sending notifications to your user.
invoice.payment_failed	Occurs whenever an invoice payment attempt fails, due either to a declined payment or to the lack of a stored payment method. Use for sending notifications to your user or restricting access.

Setting up Stripe to send events to your app

You can add your app as an endpoint from the Stripe Dashboard. You should set up an 'Account' type webhook endpoint and configure the events listed above. For more details on setting up your app as an endpoint, read here.