Overview
Previously, what we called webhooks or push notifications only affected recurring billing. Our new system is used throughout our entire system, including actions you take in the API and through your Dashboard. The new system is composed of two parts, events and webhooks.
Events are first class objects in our API; you can list and retrieve them like
other resources. Each event represents something that happened in your account, and events have
a type associated with them that tells you what happened. Examples include
a new successful charge, which will result in a charge.succeeded event being created.
Webhooks refer to Stripe sending event objects directly to your server. In your webhook settings you can add one or more URLs that Stripe will send POST requests to anytime a new event is created. The status of your webhooks is displayed along side each event's information in your dashboard.
Upgrading your invoice_ready webhook
One of the most common uses of our legacy webhook system was to listen for invoice_ready
webhooks and then respond with an amount to be added to the invoice. Our new webhook system makes this
use case easier and far more reliable.
To implement the same functionality, you should listen for events with a type of invoice.created.
These events are created every time a new invoice is generated in Stripe, and include the details of that invoice.
When a new invoice is created, Stripe waits until one hour after all webhooks have returned a 200 status code
before trying to pay the invoice (or, three days if we're unable to receive a response). The one hour delay
gives you the opportunity to create new invoice items using the standard API method. By providing the ID of the invoice sent to you in the invoice.created event as the value of the invoice parameter,
Stripe will add the invoice item to that existing invoice instead of leaving the invoice item pending
for the upcoming invoice.
Upgrading recurring_payment_failed and subscription_final_payment_attempt_failed webhooks
When Stripe tries to pay an invoice and the attempt fails we will now send an
invoice.payment_failed event type, where previously we sent
recurring_payment_failed. The invoice's description will
include details about how many times we have attempted to pay it thus far, and
when our next payment attempt will happen. Stripe no longer sends a separate
event for subscription_final_payment_attempt_failed. When a
payment failed event occurs and the description of our next payment attempt is nil,
that means we won't try to pay the invoice again.
Unlike before, we also now send events related to the actual result of the final payment attempt
failing. Based on your account settings, we'll let you know how the relevant subscription has
been affected in a customer.subscription.updated or
customer.subscription.deleted event.
United States
