Using webhooks with subscriptions

Learn to use webhooks to receive notifications of subscription activity.

Stripe sends notifications to your app using webhooks. Although webhooks can be used for many purposes, they are especially important when using subscriptions, where most activity occurs asynchronously.

To use webhooks with your subscriptions:

Follow the general webhooks guide to create your webhook endpoint and configure it in your Stripe account.
Test your webhook endpoint to confirm that it's working.

After taking those basic steps, read about common uses for webhooks with subscriptions. You should also note how webhooks affect when invoices are finalized.

Common uses of webhooks with subscriptions

As subscriptions are an automatically recurring process, most subscription activity is triggered by Stripe: the generation of invoices, attempted payment on invoices, and cancellation of subscriptions due to failed payment. For each of these events—and more—you’ll likely want to take steps on your site.

Four common uses of webhooks with subscriptions include:

Handling invoice payment failures
Handling payments that require additional action
Tracking active subscriptions
Catching subscription state changes

Handling payment failures

Webhook notifications provide a reliable way to be notified of payment failures on subscription invoices. A payment failure can be a temporary problem—the card issuer declined this charge but may allow the automatic retry—or indicative of a permanent blocker, such as not having a usable payment method. When payments fail, an invoice.payment_failed event is sent and the status of the PaymentIntent is requires_payment_method. For more details on how to handle payment failures, see the How subscriptions work page.

Handling payments that require additional action

Some payment methods may require additional steps, such as customer authentication, to complete. When an invoice’s payment requires additional action, invoice.payment_action_required and invoice.payment_failed events are sent and the status of the PaymentIntent is requires_action. Upon receiving these events, your application will need to notify the customer to complete the required action. For details on how to handle these payments, read the How subscriptions work page.

Tracking active subscriptions

Subscriptions require more coordination between your site and Stripe than one-time payments do. In the subscription model, a customer’s continued access to your product or service is determined by the success or failure of automatic, recurring payments. Take, for example, a site where a subscription provides access to the site’s content.

On the site, you’d store each user’s login credentials (e.g., email address and password, in an appropriately secure, encrypted format). You’d also store a value representing the customer’s access expiration date (i.e., the customer has paid for access until this point).

When a customer subscribes, you would initially store this timestamp value (it may be called current_period_end), adding perhaps a day or two for leeway. When the customer logs in, you’d verify the login credentials and check the current_period_end timestamp to confirm that it’s still in the future, and therefore an active account.

When the subscription is renewed (i.e., when Stripe bills the customer and they are charged again) your site is notified via webhooks of the additional payment:

A few days prior to renewal, your site receives an invoice.upcoming event at the webhook endpoint. You can listen for this event to add extra invoice items to the upcoming invoice.
Your site receives an invoice.paid event.
Your webhook endpoint finds the customer for whom payment was just made.
Your webhook endpoint updates the customer’s current_period_end timestamp in your database to the appropriate date in the future (plus a day or two for leeway).

Catching subscription state changes

Although most subscriptions exist in an active state, state changes are common and are something you need to prepare for. A few examples include:

When a subscription is about to move from trialing to active, you’ll receive a customer.subscription.trial_will_end event. Upon receiving this event notification, your webhook script might ensure there’s a payment method on the customer so they can be billed, and optionally notify the customer that a charge is forthcoming.
When a subscription changes to past_due, your webhook script could email you about the problem so you can reach out to the customer, or the script could email the customer directly, asking them to update their payment details.
When a subscription changes to canceled or unpaid, your webhook script should ensure the customer is no longer receiving your products or services.

Webhooks and finalizing invoices

Registering a webhook endpoint has an important effect on invoices, predominantly those created for subscriptions. When automatic collection is enabled, Stripe automatically finalizes and begins automatic collection of the invoice.

Stripe waits an hour after receiving a successful response to the invoice.created event before attempting payment. If a successful response isn’t received within 72 hours, Stripe attempts to finalize and send the invoice.

In case you want to treat one-off invoices differently than subscription invoices, check the subscription property in the webhook body. This indicates if the invoice was created for a subscription (or not).

In live mode, if your webhook endpoint does not respond properly, Stripe continues retrying the webhook notification for up to three days with an exponential back off. In test mode, we retry three times over a few hours. During that time, no payment will be attempted unless a successful response is received. We’ll also notify you via email that the webhook is failing.

This behavior applies to all webhook endpoints defined on your account, including cases where a Connect application or other third-party service is having trouble handling incoming webhooks.