stripe invoice created vs invoice finalized which webhook to listen for

Not specified by the original author.

TL;DR

invoice.created fires when the draft exists (useful for pre-finalize logic like invoice.upcoming warnings or custom validation); invoice.finalized fires when the invoice becomes real and billable (the trigger for fulfillment, revenue recognition, and dunning). Most post-billing automation belongs on invoice.finalized; use invoice.created only when you need the draft window. Listening to both without distinguishing them double-triggers flows.

Steps

1. List what each automation needs: draft-time intervention vs post-finalize action. Expected: Each listener gets a justified event.

2. Put pre-finalize logic (warnings, validation, edits) on invoice.created. Expected: Draft-window work runs before the invoice is real.

3. Put fulfillment, accounting entries, and dunning on invoice.finalized. Expected: Real-invoice work runs exactly once, on a real invoice.

4. Guard handlers with the invoice status so a misrouted event cannot double-fire. Expected: Defense in depth against duplicate processing.

5. Document the event map for your team so new automations pick the right hook. Expected: Future work inherits the correct pattern.

When to use

• You wire new invoice automation
• Handlers fire twice or at the wrong time
• You need draft-window vs finalized semantics

When not to use

• You handle payment outcomes (use invoice.payment_succeeded or failed)
• You need subscription lifecycle events (different webhook family)
• You only care about disputes (different family)

Compatibility

Stripe webhooks; invoice.created and invoice.finalized event types. All API versions with Billing.

Variant phrasings

### Stripe invoice.created vs finalized

### which invoice webhook to use Stripe

### invoice finalized webhook fulfillment

Root cause

The two events bracket the draft-to-real transition: created announces intent (the invoice might still change or never finalize), finalized announces commitment (number assigned, totals locked). Automation that acts on intent as if it were commitment fulfills orders for invoices that never bill.

Edge cases

• Manually finalized invoices fire finalized whenever you call it, which can be much later than created
• Voided drafts never fire finalized; handle the void path in your state machine
• Test clocks let you rehearse the full created-to-finalized sequence

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_eBWLsrkWHqXeZP2tFF67JQ

Resolved from the public thread: https://vectle.com/posts/pst_eBWLsrkWHqXeZP2tFF67JQ

Thread query: Stripe invoice.created vs invoice.finalized: which webhook to listen for

TL;DR: invoice.created fires when the draft exists (useful for pre-finalize logic like invoice.upcoming warnings or custom validation); invoice.finalized fires when the invoice becomes real and billable (the trigger for fulfillment, revenue recognition, and dunning). Most post-billing automation belongs on invoice.finalized; use invoice.created only when you need the draft window. Listening to both without distinguishing them double-triggers flows.

Not specified by the original author.

TL;DR

For failed subscription or invoice payments, handle invoice.paymentfailed: it carries the invoice, the customer, and the billing context your dunning flow needs. charge.failed is the lower-level event about a single charge attempt, useful for analytics or decline-code dashboards but missing the invoice linkage. Handling both usually double-counts. Pick invoice.paymentfailed as the recovery trigger and subscribe to charge.failed only for payment-ops telemetry.

The query

Stripe "invoice.payment_failed" vs "charge.failed": which webhook to handle

Use this when

• Deciding which Stripe webhook drives your dunning flow
• You get duplicate failed-payment alerts from both events
• Building a decline-code dashboard for payment ops

Not for

• Successful payments (use invoice.paid / invoice.payment_succeeded)
• Disputes or refunds (different event families entirely)

Steps

1. Subscribe to invoice.payment_failed and inspect its payload: invoice id, customer, attempt count. Expected output: You have everything the dunning flow needs in one event.

2. Route it to your recovery queue: email the customer, open the portal link, schedule retries. Expected output: Failed invoices enter recovery automatically.

3. If you want decline-code telemetry, also listen to charge.failed and join on payment_intent. Expected output: Your dashboard gets decline reasons without driving recovery.

4. Dedupe: do not send customer emails from both handlers. Expected output: Customers get one recovery email, not two.

5. Verify the signature on both endpoints and log the event id for idempotency. Expected output: Replays do not double-trigger the flow.

Variant phrasings

Stripe invoice.payment_failed vs charge.failed

which webhook for failed subscription payment Stripe

Stripe dunning webhook invoice payment failed

Root cause

invoice.payment_failed sits at the billing layer and charge.failed at the payments layer; Stripe emits both because one failed invoice can involve multiple charge attempts. Recovery logic belongs at the billing layer where the customer and invoice context live.

Edge cases

• Smart retries can emit several charge.failed events for one invoice.payment_failed; count at the invoice level
• invoice.payment_failed also fires for non-card failures like no payment method, so do not assume a decline

Provenance

Resolved from the public thread: https://vectle.com/posts/pstAH-vdHJyS2viUoL8C6NNQ

Resolved from the public thread: https://vectle.com/posts/pstAH-vdHJyS2viUoL8C6NNQ

Thread query: Stripe "invoice.payment_failed" vs "charge.failed": which webhook to handle

TL;DR: For failed subscription or invoice payments, handle invoice.paymentfailed: it carries the invoice, the customer, and the billing context your dunning flow needs. charge.failed is the lower-level event about a single charge attempt, useful for analytics or decline-code dashboards but missing the invoice linkage. Handling both usually double-counts. Pick invoice.paymentfailed as the recovery trigger and subscribe to charge.failed only for payment-ops telemetry.

Not specified by the original author.

TL;DR

Between this event and finalization, you may still change it. Decide fast whether this invoice needs changes: metered usage to add as invoice items, one-off credits, discounts, custom metadata your accounting needs.

Steps

1. A new invoice was created in draft state. Between this event and finalization, you may still change it. After finalization, the invoice is locked and the money is attempted.
2. Decide fast whether this invoice needs changes: metered usage to add as invoice items, one-off credits, discounts, custom metadata your accounting needs.
3. Make the changes via the API immediately, in the handler or in a job it enqueues within minutes. The draft window is short (roughly an hour for automatically created subscription invoices).
4. Do not provision or entitle anything here. No money has moved. This event is for invoice surgery, not fulfillment.
5. Return 200.
6. A slow handler. If your job queue takes an hour to pick up the invoice-tweaking job, the invoice finalized without your changes and you are issuing credit notes instead. Keep this path fast or skip it. The other trap: adding invoice items to every invoice.created without checking whether the invoice is a subscription renewal or a one-off; the logic usually only applies to one of them.
7. - invoice.finalized is the event that says the window closed. If you need a "no more changes" signal, listen for that, not for time passing.

• Draft invoices created manually in the Dashboard also fire this event. Your handler should distinguish subscription-cycle invoices (automatic) from manual ones before applying automatic tweaks.

When to use

You are seeing this: A new invoice was created in draft state. Use this skill when you run into "Stripe event: invoice.created, your last chance to touch the invoice before it finalizes".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Stripe's event reference says invoice.created occurs whenever a new invoice is created, and points to Using Webhooks with Subscriptions for how webhooks can affect it. Verified live at https://docs.stripe.com/api/events/types. Finalization locks the invoice; invoice.finalized is the documented end of the draft window.