Sign in
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
Security
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support
Overview
Overview
Customers
Products and Prices
Tax Rates
Customer portal
Quotes
Start with a use case
Subscriptions with Checkout
Fixed-price subscriptions with Elements
Metered billing with Elements
Per-seat billing with Elements
Manage subscriptions
How subscriptions work
Subscription webhooks
Change subscriptions
Strong Customer Authentication (SCA)
Improved tax support
Invoices API updates
Migrating to Prices
Additional features
Testing
Add payment methods
Bacs Direct Debit in the UK
BECS Direct Debit in Australia
SEPA Direct Debit in the EU
Invoice customers
How invoices work
Create an invoice
Customize invoices
Hosted invoice page
Additional features
Revenue recognition
Overview
Reports
Methodology
Examples
Overrides
Testing
Subscriptions and invoices
Subscription webhooks
billing
·
HomePaymentsSubscriptions and invoices

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:

  1. Follow the general webhooks guide to create your webhook endpoint and configure it in your Stripe account.
  2. 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.

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 How subscriptions work.

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, see How subscriptions work.

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:

  1. 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.
  2. Your site receives an invoice.paid event.
  3. Your webhook endpoint finds the customer for whom payment was just made.
  4. 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 whether the invoice was created for a subscription.

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.

To summarize: If Stripe fails to receive a successful response to invoice.created, then finalizing all invoices with automatic collection will be delayed for up to 72 hours. Responding properly to invoice.created includes handling all webhook endpoints configured for your account, along with the webhook endpoints of any platforms to which you’ve connected. Updating a subscription in a way that synchronously attempts payment (on the initial invoice, and on some kinds of updates) does not cause this webhook wait.

Next steps

  • Lifecycle and Events
  • Testing Subscriptions
  • Events API
Was this page helpful?
Questions? Contact us.
Developer tutorials on YouTube.
You can unsubscribe at any time. Read our privacy policy.
On this page
Common uses of webhooks with subscriptions
Webhooks and finalizing invoices
Next steps