Using webhooks with subscriptions

You receive notifications from Stripe in your app through webhook events. Process these events at a webhook endpoint or other destinations like Amazon EventBridge or Azure Event Grid by creating an event destination. A subscription integration requires a destination that handles webhook events, because most subscription activity happens asynchronously.

To use webhooks with your subscriptions:

1. Create a webhook endpoint in your app.
2. Register your webhook endpoint in Workbench.
3. Add logic to handle Stripe events. For subscriptions, these include payment failures and subscription status changes (like moving from trial to an active status). You can use the webhook quickstart to build a minimal webhook endpoint. Be sure to verify that incoming events are from Stripe.
4. Test your webhook endpoint to confirm that its working as expected.

If your application runs on AWS, you can configure Stripe to send events directly to AWS EventBridge in your AWS account. If your application runs on Azure, you can configure Stripe to send events directly to Azure Event Grid in your Azure subscription.

Handle payment failures

Events provide a reliable way for Stripe to notify you of payment failures on subscription invoices. Some payment failures are temporary-for example, a card issuer might decline the initial charge but allow an automatic retry. Other payment failures are final and require action, like not having a usable payment method for the customer.

Handle payments that require additional action

Some payment methods might require additional steps to complete, such as customer authentication. If you receive these events, your app must notify the customer to complete the required action. To learn how to handle events that require additional action, read the subscription overview guide.

Handle refund events

When Stripe issues a refund, it sends a charge.refunded event that contains the updated Charge object. To identify which subscription the refunded charge belongs to, follow these steps:

1. Retrieve the PaymentIntent ID from the Charge using the payment_intent field.
2. Use the List all payments for an invoice endpoint with payment.payment_intent set to the PaymentIntent ID.
3. The returned InvoicePayment contains an invoice field with the associated Invoice ID.
4. Retrieve the Invoice and use its subscription field to get the Subscription associated with the refund.

Track active subscriptions

Subscriptions require coordination between your site and Stripe-the success or failure of a customers recurring payments determines whether they can continue to access your product or service.

For typical integrations, you store customers credentials and a mapped timestamp value that represents the access expiration date for that customer on your site when a customer subscribes. When the customer logs in, you check whether the timestamp is still in the future. If the timestamp is in the future when the customer logs in, the account is active and the customer should still have access to the service.

When the subscription renews, Stripe bills the customer and tries to collect payment by either automatically charging the payment method on file, or emailing the invoice to customers. Stripe notifies your site of the invoice status by sending a webhook event:

1. Your site receives an invoice.paid event.

   • When automatically charging a payment method, your site first receives an invoice.upcoming event to your configured webhook endpoint a few days before renewal. You can listen for this event to add extra invoice items to the upcoming invoice. If collection_method=send_invoice, Stripe doesnt send an invoice.upcoming event.

2. Your application finds the customer the payment was made for.

3. Your application updates the customers access expiration date in your database to the appropriate date in the future (plus a day or two for leeway).

Catch subscription status changes

Make sure that your integration properly monitors and handles transitions between the subscription statuses described in the following table.

Some status changes require special attention:

• A few days before a trial ends and the subscription moves from trialing to active, you receive a customer.subscription.trial_will_end event. When you receive this event, verify that you have a payment method on the customer so you can bill them. Optionally, notify the customer that they will be charged.

• When a subscription changes to past_due, notify the customer directly and ask them to update their payment details. Stripe offers several features that help automate this process-read more about revenue recovery.

• When a subscription changes to canceled or unpaid, revoke access to your product.

Webhook endpoints and invoices

Register a webhook endpoint to keep track of invoice statuses. Your subscription integration depends on correctly finalizing invoices and properly handling invoice finalization failures.

When you enable automatic collection, Stripe automatically finalizes and begins automatic collection of the invoice.

• If Stripe fails to receive a successful response to invoice.created, we delay finalizing all invoices with automatic collection for up to 72 hours, excluding those where you have set a custom scheduled finalization time.
• Responding properly to invoice.created includes handling all webhook endpoints configured for your account, along with the webhook endpoints of any platforms that youve connected to. This doesnt include any webhook endpoints configured in an organization. While you can listen to invoice.created at the organization, a successful response doesnt affect invoice finalization when using automatic collection.
• Updating a subscription in a way that synchronously attempts payment (on the initial invoice, and on some kinds of updates) doesnt cause this delay.
• Invoice finalization failure prevents payment collection for the invoice. Make sure you listen for the invoice.finalization_failed event in your webhook endpoint.

Webhook events related to invoice finalization

See a complete list of invoice event types.

Successful invoice finalization

Stripe waits an hour after receiving a successful response to the invoice.created event before attempting payment. If we dont receive a successful response within 72 hours, we attempt 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 doesnt respond properly, Stripe continues retrying the webhook notification for up to 3 days with an exponential back off. In a sandbox, we retry three times over a few hours. During that time, we wont attempt to charge the customer unless we receive a successful response. Well also send you an email to notify you 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.

Invoice finalization failure

If Stripe cant finalize an invoice, it sends a invoice.finalization_failed event to your webhook endpoint. Subscriptions remain active if invoices cant be finalized, which means that users may still be able to access your product while youre not able to collect payments. Make sure to take action on invoices that fail finalization. You cant collect payments on an invoice that isnt finalized.

To determine why the invoice finalization failed, look at the Invoice objects last_finalization_error field, which provides more information about the failure, including how to proceed.

If youre using Stripe Tax, check if the automatic_tax.status field is requires_location_inputs, indicating that the address details are invalid or insufficient. If Stripe Tax cant find a recognized customer location, we cant finalize the invoice. Learn how to handle invoice finalization failures.

Testing

To test your webhook endpoint or event destination, choose one of these two options:

1. Perform actions in a sandbox that send legitimate events to your event destination. For example, to trigger the charge.succeeded event, you can use a test card that produces a successful charge.
2. Trigger events using the Stripe CLI or using Stripe for Visual Studio Code.