Webhooks and Retries (Dunning)

Your product managers and Engineering organization typically complete this phase, which Stripe estimates to typically take a week.

Webhooks overview

You can use webhooks to notify your customer, application, or website about things that happen asynchronously behind the scenes. A webhook endpoint is essentially a script that sits on your own server and listens for events that Stripe sends it.

Key webhooks for launch

For a SaaS or services app/website, a common use case for webhooks is to revoke access to a particular set of features when a payment fails. Similarly, with a retail subscription, you might want to prevent a product shipment if a payment fails.

When such payment failures occur, Stripe creates an invoice.payment_failed event that’s sent to your webhook endpoint. You can use this event to update a report, send a notification, cancel delivery of a particular set of features, or take other actions.

The invoice.payment_failed event is generally the most important webhook for which subscription businesses should set up an endpoint. This is true even if you are just building an MVP (minimum viable product).

For a description of Stripe’s subscription lifecycle, and a complete list of subscription events that you can listen for, see Billing Lifecycle and Events. For guidance on webhooks for billing, see Using Webhooks with Subscriptions.

The charge.dispute series of webhooks (charge.dispute.created, charge.dispute.updated, etc.) can also be helpful, since disputes happen asynchronously, and you will want to make sure that you don’t miss the evidence submission deadline.

Your team can also opt to have Stripe automatically email you when disputes happen. Be sure to set this up in your Dashboard’s Email settings.

Contacting customers for failed charges

Another useful and common practice is to send email notifications to your customers if their subscription payment fails, prompting them to update their payment information. You can enable this behavior in your Dashboard’s Automatic collection settings.

If you want to customize this email beyond the options that Stripe provides, you could instead monitor invoice.payment_failed webhooks to trigger your own custom emails. These emails typically link the customer to a form where they can update their payment method. See our complete Sending Emails for Failed Payments recipe for building out this functionality.

If you want to build dunning (retries) logic for declined charges, you can use your Dashboard’s Automatic collection settings to dictate how Stripe responds when an invoice payment fails or becomes past due. The settings for automatic payment and manual payment are configured independently; for details, see Subscription settings and recovery.

Next steps

Was this page helpful?

Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

On this page