Using Webhooks with Subscriptions

    Learn to use webhooks to receive notifications of subscription activity. If you need help after reading this, search our documentation or check out answers to common questions. You can even chat live with other developers in #stripe on freenode.

    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:

    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 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 paid.

    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 bank 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 set this timestamp value (it may be called active_until) to one month from now, plus perhaps a day or two for leeway. When the customer logs in, you’d verify the login credentials and check the active_until 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.
    2. Your site receives an invoice.payment_succeeded event.
    3. Your webhook endpoint finds the customer for whom payment was just made.
    4. Your webhook endpoint updates the customer’s active_until timestamp in the database to another month 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_end event. 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. If you’re using webhooks, Stripe waits to receive a successful response to the invoice.created event before attempting payment.

    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. This includes if a Connect application is having problems with its webhooks handling.

    Next steps

    Congrats! You’ve learned how to use webhooks with subscriptions. Some documentation you might want to read next: