Webhooks are a tool Stripe uses to notify your site of account events. Although webhooks can be used for many purposes, they are especially important when using subscriptions, where most activity occurs asynchronously and behind the scenes.
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 it's working.
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.
Three common uses of webhooks with subscriptions include:
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 source.
We’ve written up a recipe that walks through accepting and processing payment failure notifications so you can automatically email your customer when it happens.
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).
If a customer subscribes to a monthly plan, 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.upcomingevent at the webhook endpoint.
- Your site receives an
- Your webhook endpoint finds the customer for whom payment was just made.
- Your webhook endpoint updates the customer’s
current_period_endtimestamp 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’ll want to be prepared to address. Just a few examples of changes and potential reactions include:
- When a subscription is about to move from trialing to active, you’ll receive a
customer.subscription.trial_will_endevent. Upon receiving this event notification, your webhook script might ensure there’s a payment source 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 payment attempts
Registering a webhook endpoint has an important effect on your subscriptions. Without webhooks, Stripe automatically attempts to pay an invoice approximately one hour after it’s generated, unless it is the first invoice created after a subscription is created or updated. If you’re using webhooks, Stripe waits to receive a successful response to the
invoice.created event before attempting payment.
In the webhook body, you should check for the
subscription property on the invoice to be set. This indicates that the invoice was created through a subscription. One-off invoices (created through the Dashboard or API) also send
invoice.created webhooks, but they won’t have the
If your webhook endpoint does not respond properly, Stripe continues retrying the webhook notification every hour for up to 72 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.
If the webhook notification hasn’t succeeded after 72 hours, Stripe attempts to pay the invoice anyway.
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.
Congrats! You’ve learned how to use webhooks with subscriptions. Some documentation you might want to read next: