Handle billing webhook replay without regressing account state

Verify the billing channel independently

Billing callbacks use their own provider signature boundary. Lupin’s billing webhook endpoint verifies the Stripe signature over the raw body using its configured signing secret and a five-minute timestamp window. The customer’s API bearer key is not the authentication mechanism for this route.

Preserve exact request bytes through reverse proxies and framework middleware until verification completes. A parsed and reserialized body can differ from the signed bytes. Do not treat a recognizable subscription ID or a request from a plausible network address as an alternative to signature validation.

Deduplicate event delivery, not just requests

A provider can deliver the same event more than once. Lupin records processed billing event IDs durably so a repeated delivery can be acknowledged without repeating its state transition. A local in-memory set is insufficient when requests reach different workers or a process restarts.

Keep event identity distinct from the user’s checkout or plan-change intent. Several events can describe one subscription transition, and one event can be redelivered many times. A checkout success redirect is user navigation; it does not establish a verified subscription state or grant the corresponding entitlement.

Protect newer subscription evidence

Delivery order can differ from event creation order. The billing implementation uses saved event time and guarded account revision updates to avoid allowing an older subscription event to blindly overwrite newer account state. Inspect the accepted account revision and last event metadata when diagnosing a seeming rollback.

A replay with no state change can therefore be healthy. A signed old event that conflicts with newer evidence should not force the account backward merely because it arrived later. Reconciliation must examine the verified subscription and current durable account state rather than apply callbacks in arrival order alone.

Event timestamps are not a total order: separate events can share a timestamp. The handler retrieves and validates current provider subscription data before persisting the transition; event-ID deduplication and guarded revisions address different parts of the recovery problem.

Let incomplete accounting remain retryable

Some billing events require more than a subscription status update. Lupin’s invoice readiness check can return billing_usage_pending while relevant reservations or meter exports remain unresolved. A delivery should not be marked complete simply to stop provider retries if the accounting precondition has not been satisfied.

Investigate the pending work through its original identities and periods. Repeating the product action, fabricating a new meter event or changing a customer’s plan does not settle the original accounting. A durable retry is valuable here because it gives the system another chance after the underlying condition recovers.

Exercise replay and ordering locally

Use synthetic signed events and an isolated database to cover duplicate delivery, stale timestamp, modified raw bytes, an older subscription event and an invoice with pending exports. Assert both the acknowledgment and durable account state. A successful HTTP response alone cannot demonstrate correct entitlement behavior.

Keep secrets, invoice details and customer identifiers out of ordinary logs. A bounded operator record can include event type, processing result, state revision and private correlation reference. These checks establish local handler behavior only; complete payment-flow validation still belongs in the provider’s test environment before live activation.

Sources & verification

Reviewed against the checked-in Lupin implementation and official reference documentation on 2026-11-05. Operational examples are illustrative; no live paid action, provider mutation or external message was executed.

• Lupin billing, metering and retained storage ↗Checked 2026-11-05
• Stripe webhook delivery and signature verification ↗Checked 2026-11-05

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.