How to Intercept and Recover Failed Stripe Invoices via Signed HMAC Webhooks

What actually happens when a Stripe invoice fails

When a subscription invoice cannot be collected, Stripe finalises the invoice, attempts the charge, receives a decline from the issuer and emits an `invoice.payment_failed` event. The invoice moves to `open` with a `next_payment_attempt` timestamp if Smart Retries is enabled, or to `uncollectible` once the retry schedule is exhausted. Nothing in that sequence contacts your customer in your voice, on your schedule, on a channel they read.

That gap is the entire recovery opportunity. The decline itself is rarely a decision — the overwhelming majority of failed subscription charges are involuntary: a card expired, a balance was short for a few hours, an issuer flagged a recurring merchant it did not recognise, or a 3-D Secure challenge timed out while the customer was asleep. The customer still wants the product. They simply do not know the charge failed.

An interception layer sits on the event stream, not on the money. It never captures a card, never issues a refund, never mutates a subscription. It reads the failure, decides what kind of failure it is, and starts a conversation that carries the fix.

The three events worth subscribing to

`invoice.payment_failed` is the primary signal. It carries the invoice ID, the customer, the amount due, the currency, the attempt count and — critically — the `last_finalization_error` or the charge's `outcome` object containing the decline code.

`charge.failed` is the lower-level twin. Subscribe to it when you also bill one-off charges outside the invoicing system, or when you want the issuer's `network_status` and `seller_message` for diagnostics that the invoice event summarises away.

`customer.subscription.updated` closes the loop. When a subscription transitions to `past_due` or `unpaid` you know the retry schedule has moved, and when it returns to `active` you know the recovery converted. Without this third event you can send messages but you cannot honestly report a recovery rate.

Verifying the signature without opening a hole

Stripe signs every webhook with an HMAC-SHA256 over a payload built from the timestamp and the raw request body, delivered in the `Stripe-Signature` header. Three implementation details separate a correct verifier from a vulnerable one.

First, compute the HMAC over the raw body bytes exactly as received. If your framework has already parsed the JSON and you re-serialise it, key ordering and whitespace will differ and every signature will fail — or worse, you will be tempted to skip verification to make the endpoint work.

Second, compare with a timing-safe function. A plain `===` comparison returns faster on an early byte mismatch, and that timing difference is enough to forge a signature byte by byte given enough attempts. Use `crypto.timingSafeEqual` over equal-length buffers.

Third, enforce the timestamp tolerance. Reject anything older than five minutes to kill replay attacks, and reject before you touch the database so an unverified payload never becomes a row.

Idempotency: the failure mode nobody tests

Stripe retries webhook deliveries for up to three days when your endpoint does not return a 2xx quickly. It also occasionally delivers the same event twice under normal conditions. If your handler writes a failure row and enqueues a message on every delivery, one flaky deploy turns into three identical dunning messages to the same customer within an hour — the fastest way to convert an involuntary churn into a voluntary one.

Store the Stripe event ID with a unique constraint and treat the insert conflict as success. Return 200 immediately after the row is durable and do the message generation asynchronously; a handler that blocks on an AI call or an outbound send will eventually exceed Stripe's timeout and trigger the very retries you are trying to deduplicate.

The same discipline applies to the outbound side. Key each dispatch on `(event_id, channel, attempt)` so a worker restart replays the queue without replaying the message.

Routing by decline code, not by calendar

The single largest improvement over stock dunning is refusing to treat every failure the same. Stripe hands you the reason; use it.

`insufficient_funds` should wait roughly 48 hours. The balance was short at the moment of capture and typically is not short two days later, especially if the retry lands after a payday window in the customer's country. Recovery in the 55-70% band is normal.

`expired_card` should not be retried at all until the card is replaced. No retry schedule can fix a dead credential. The lever is a one-click update link, above the fold, with no login wall — which is why this code posts the highest recovery of all, commonly 70-85%.

`do_not_honor` is an unexplained issuer block. Retry at around 36 hours, but ask for an alternate card in the first message rather than the third; grinding retries against a blocking issuer risks merchant-level throttling.

`authentication_required` is time-sensitive. The 3-D Secure confirmation link expires, so send it within minutes on the fastest channel you have and retry at 24 hours.

Choosing the channel before you write the copy

Teams spend weeks A/B testing dunning subject lines while sending on a channel that four out of five customers never open. Transactional billing email lands in the 18-25% open range and often in a Promotions tab unless the sending domain is DKIM-signed, SPF-aligned and warmed.

WhatsApp Cloud API, sending from your own Meta business number with an approved utility template, reads in the 90%+ range with a median response window under fifteen minutes. The economics are straightforward: Meta bills you per conversation directly, and a single recovered $80 subscription pays for hundreds of them.

The correct architecture is not WhatsApp instead of email; it is both, sequenced. Email first for expired cards, because the update link benefits from a full-width page. WhatsApp first for authentication and insufficient funds, because speed is the whole game.

Writing the message the decline code implies

Generic 'your payment failed' copy forces the customer to diagnose their own billing problem. Naming the cause in the first line — the card ending 4242 expired, the bank returned a temporary hold, your balance was short at the moment we charged — converts measurably better because it tells the reader exactly which two-minute action closes the loop.

Keep the message transactional. No marketing header, no unsubscribe-flavoured footer, no discount. A dunning message that looks like a campaign gets filtered like a campaign.

State the retry time explicitly. 'We will try again on Thursday morning' lets a customer with a temporary shortfall simply top up and do nothing else, which is the cheapest recovery path that exists.

Measuring recovery honestly

The metric that matters is recovered revenue as a share of at-risk revenue in the same cohort, measured over a fixed window — fourteen days is the standard. Anything else flatters the numbers.

Track four supporting series: time to first touch, time to recovery, recovery rate by decline code, and cost per recovered dollar. The last one is where percentage-fee vendors quietly become expensive; at scale a flat-fee recovery layer should sit well under two cents per recovered dollar, while a nine percent revenue share is roughly nine.

Attribute conservatively. If Stripe Smart Retries would have recovered the charge on its own schedule anyway, do not claim it. Run one billing cycle in shadow mode — messages off, tracking on — and use that as the baseline you measure against.

A concrete implementation checklist

Create the endpoint and register it in Stripe against the three events above. Store the signing secret as a server-side secret, never in client code, and rotate it independently of your API keys.

Verify with the raw body, timing-safe compare, five-minute tolerance. Persist the event with a unique constraint on the provider event ID. Return 200 within a second.

Derive the retry window and channel from the decline code at ingestion and persist them on the row, so a scheduler restart cannot lose the plan. Generate copy asynchronously with a deterministic template fallback so a message always exists even when an AI tier is unavailable.

Cap the cadence at three or four touches across seven to ten days. Attempts one and two carry roughly eighty percent of all recovered revenue; a fifth attempt mostly buys complaints.

Data model: what to persist per failure

Persist one row per failure event containing the provider event ID, the invoice and customer identifiers, the amount and currency, the raw decline code, the normalised bucket, the computed retry timestamp, the chosen channel order and the subscription state at ingestion. Everything downstream reads from this row rather than re-querying Stripe, which keeps the pipeline resilient to API rate limits and outages.

Store dispatch attempts in a child table keyed on the failure row, one per channel per touch, with the template used, the generated body, the provider message ID and the delivery result. This is what lets you answer, six weeks later, exactly why a specific customer received a specific sentence.

Never store card numbers, CVVs or tokens capable of initiating a charge. Brand and last four are enough to write a precise message, and holding nothing else is what keeps the whole recovery layer outside PCI scope.

Failure modes to rehearse before launch

Duplicate delivery: replay the same event twice in staging and confirm exactly one row and one message result. Out-of-order delivery: deliver the success event before the failure event and confirm no message is sent. Late recovery: recover the invoice after a message is queued and confirm the dispatch is cancelled at the pre-send state check.

Provider outage: block outbound model and messaging calls and confirm the deterministic template path still produces and queues a message. Secret rotation: rotate the signing secret and confirm the endpoint rejects the old signature with a 401 rather than silently accepting it.

Each of these has produced a real customer-facing incident somewhere. Rehearsing them costs an afternoon and removes the entire category.

Where RRLabs fits

Revenue Recovery Labs implements this exact pipeline as a hosted layer: signed webhook ingestion, idempotent persistence, decline-code routing, a four-tier message cascade with deterministic fallback, and an audit row per dispatch carrying model, latency and recovery score.

The connection is read-only, so no write scope on your Stripe account is required and no card data crosses the boundary. Pricing is flat at $100, $250 or $500 per month with an optional $300 white-label add-on, so cost per recovered dollar falls as your recovery grows rather than scaling with it.

If you would rather build it yourself, the checklist above is the complete specification. The only parts that reliably take longer than expected are deliverability and WhatsApp template lifecycle management.