PRODUCTION GUIDE / INVOICE-PAYMENT-FAILED-HANDLER

Build an invoice.payment_failed handler that does not panic

A failed invoice is a state transition, not an immediate cancellation command.

Record the invoice and attempt

Store invoice ID, subscription ID, attempt count, next payment attempt, and event ID.

Let Stripe recovery run

Align application access with your configured retry and grace-period policy. Avoid canceling on the first failure unless that is explicitly your product rule.

Deduplicate notifications

Retry deliveries must not send repeated dunning emails. Store notification state separately from webhook receipt state.

Need the tested implementation?

The Hookproof kit includes the typed router, persistent idempotency adapters, fixtures, and deployment runbook.

GET THE $29 KIT