A card expired, the renewal failed, and the customer still has the paid plan a month later. Or the opposite: one failed attempt and your app locked them out while Stripe was still retrying. Both come from the same gap: the webhook only handles the happy path.
Stripe: "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" (Stripe docs: Using webhooks with subscriptions).
invoice.payment_failed: "A payment for an invoice failed." Stripe lists the actions you can take: notify the customer, enable Smart Retries, or update the default payment method on the subscription (source).invoice.updated: "If payment fails, paid is set to false and the status remains open. Payment failures also trigger an invoice.payment_failed event" (source).customer.subscription.updated: the subscription's status changes, for example to past_due.customer.subscription.deleted: if your settings cancel the subscription once retries run out.If your endpoint is only subscribed to checkout.session.completed and invoice.paid, none of this reaches your app, and the user keeps whatever access they had. Check the endpoint's event list in the Dashboard first.
past_due: "Payment on the latest finalized invoice either failed or wasn't attempted." "Stripe might retry payment while the subscription is past_due, but this status doesn't guarantee another payment attempt." Stripe's advice: "When a subscription changes to past_due, notify the customer directly and ask them to update their payment details" (source). Whether you keep access during this grace period is your business decision.unpaid: the subscription "continues to generate invoices but doesn't attempt payment. Revoke access to your product when the subscription is unpaid because Stripe already attempted and retried payment while the subscription was past_due" (source).canceled: Stripe: "When a subscription changes to canceled or unpaid, revoke access to your product" (source).What happens after the last retry is a Dashboard setting. "If an invoice is still unpaid after all payment retries, you can configure the subscription to move to canceled or unpaid, or to remain past_due" (source). The retry settings page offers the same three options: cancel the subscription, mark it as unpaid, or leave it past-due (Stripe docs: Smart Retries).
So if the setting is "leave the subscription past-due" and your app only removes access on canceled, a customer whose card died can keep the plan indefinitely. Pick one rule and write it down: for example, "access continues while past_due; revoke on unpaid or canceled", with the Dashboard set to cancel or mark unpaid at the end of retries.
How long retries run is also a setting. "For new Stripe accounts, Stripe enables Smart Retries by default and configures it for up to 8 retries within 2 weeks." Stripe doesn't retry payments if, among other cases, "No payment methods are available" or "The issuer returned a hard decline code" (source).
attempt_count: "indicates how many attempts have been made so far" (source).next_payment_attempt: "When you enable dunning, the next_payment_attempt attribute indicates when the next collection attempt will be." If you use automations, Stripe says it "is no longer set in invoice.payment_failed webhooks but is set in invoice.updated webhooks" (source).hosted_invoice_url: "The URL for the hosted invoice page, which allows customers to view and pay an invoice" (Stripe API: The Invoice object). Link it from an in-app banner so the customer can fix the card without contacting you.Stripe can also email the customer for you: with "Send emails when card payments fail" turned on in the revenue recovery settings, "Stripe automatically sends an email to your customer after each failed payment" (Stripe docs: Customer emails).
invoice.payment_failed, invoice.paid, customer.subscription.updated and customer.subscription.deleted.status. Don't infer the status from the event type, and don't depend on event order (events out of order).invoice.payment_failed, also store hosted_invoice_url so the app can show "Your payment failed: update your card".// After verifying the signature on the raw body
const SUB_EVENTS = ['invoice.paid', 'invoice.payment_failed',
'customer.subscription.updated', 'customer.subscription.deleted'];
if (SUB_EVENTS.includes(event.type)) {
const obj = event.data.object;
const subId = obj.object === 'subscription'
? obj.id
: (obj.parent?.subscription_details?.subscription ?? obj.subscription);
if (subId) {
const sub = await stripe.subscriptions.retrieve(typeof subId === 'string' ? subId : subId.id);
await db.users.update({
where: { stripe_customer_id: sub.customer },
data: {
subscription_status: sub.status,
...(event.type === 'invoice.payment_failed' ? { pay_url: obj.hosted_invoice_url } : {}),
...(event.type === 'invoice.paid' ? { pay_url: null } : {}),
},
});
}
}
// One rule, used everywhere
function hasPaidAccess(user) {
return ['active', 'trialing', 'past_due'].includes(user.subscription_status); // past_due = grace period (your choice)
}
Rename the table and fields to match your app. If you don't want a grace period, drop past_due from the list. Either way, unpaid and canceled must not grant access.
Handle failed Stripe subscription renewals. 1) Make sure the webhook handles invoice.payment_failed, invoice.paid, customer.subscription.updated and customer.subscription.deleted, after signature verification on the raw body. 2) For each, get the subscription ID (subscription events: object.id; invoices: parent.subscription_details.subscription, or subscription on older API versions), retrieve the Subscription from Stripe, and save its status on the user. 3) On invoice.payment_failed also save the invoice's hosted_invoice_url; clear it on invoice.paid. 4) Create one hasPaidAccess(user) function: true for active, trialing and past_due; false for unpaid, canceled, incomplete, incomplete_expired and paused. Use it in every protected page and API route instead of a boolean is_paid flag. 5) Show a banner with the saved payment link while the status is past_due. 6) Do not change the signature check.
invoice.payment_failed with a 2xx and that the user's stored status is now past_due with the payment link saved.invoice.paid should bring the status back to active and clear the banner.status=all and resync each one (see subscription status not updating).Paste your webhook URL. WebhookProof sends 3 harmless test requests and tells you whether Stripe can reach it and whether it rejects unsigned events. If it finds a problem, the $9 fix pack gives you the exact copy-paste fix for your stack (refundable for 14 days).
Run the free checkinvoice.payment_failed. Stripe also sends invoice.updated (paid is false, status stays open) and, as the subscription changes, customer.subscription.updated with a new status such as past_due.
That is your choice. Stripe says to notify the customer and ask them to update their payment details when a subscription becomes past_due, and to revoke access when it changes to canceled or unpaid.
Usually the webhook only handles checkout.session.completed or invoice.paid, or the app only revokes on canceled while the Dashboard is set to leave subscriptions past_due after all retries. Handle invoice.payment_failed and customer.subscription.updated, store the status, and align the Dashboard setting with your access rule.
It depends on your settings. Stripe says new accounts have Smart Retries enabled by default with up to 8 retries within 2 weeks, and that it does not retry after a hard decline or when no payment method is available.
Stripe webhook not working? Check these 7 things in order · A customer paid but didn't get access. What went wrong? · No signatures found matching the expected signature for payload · Stripe webhook failing with a 307 or 308 redirect
Last reviewed 2026-11-09. WebhookProof is an independent tool, not affiliated with Stripe, Inc.. Quotes are from the linked documentation.