A reliable RevenueCat webhook architecture for recovery workflows
A recovery campaign is only as trustworthy as the event pipeline underneath it. The practical goal is not merely to receive a webhook—it is to turn changing subscription state into one durable, explainable recovery case.
Revenue recovery research
1. Store the event before acting on it
A webhook handler should acknowledge valid deliveries quickly and move business processing into a durable path. Persist the source payload, delivery time, stable event identity, app environment, and processing status before attempting to start or stop a recovery flow.
This creates an audit trail and makes retries safe. When a downstream provider is unavailable, the original subscription signal remains available for controlled reprocessing instead of disappearing inside an application log.
- Validate the request before accepting the payload
- Keep production and sandbox data clearly separated
- Record an immutable source event alongside processing status
- Return success only after the event is durably accepted
2. Make every processing step idempotent
Event delivery systems can retry. Your pipeline must assume the same event may be received more than once and ensure that repeated processing does not create duplicate recovery cases or duplicate messages.
Use a stable source-event key for ingestion and a separate case key for the customer state you are managing. This distinction lets you retain every legitimate state transition while preventing one transition from being applied twice.
The safe test is simple: if this exact event is processed again tomorrow, no customer should receive an extra message because of it.
3. Resolve events into current customer state
A single payload describes a transition, not the complete customer journey. Resolve it against the customer, product, entitlement, and any open recovery case before choosing an action.
A later renewal can close a billing-issue case. An expiration can move a canceled trial into a different recovery stage. A product change can make an earlier payment or plan message obsolete. The workflow should react to the latest known state, not whichever event happens to be processed in isolation.
- Link aliases and app-user identifiers to one customer record
- Compare event time with the latest applied subscription transition
- Close or reroute open cases when state changes
- Recheck eligibility immediately before each customer contact
4. Separate state changes from campaign actions
Keep the subscription state machine independent from the messaging provider. The state layer should decide that a customer entered, remained in, or left a recovery case. A delivery layer can then translate an eligible case into email, push, or in-app actions.
This separation makes channel changes safer and reporting clearer. It also gives support and growth teams one source of truth when a campaign provider reports delivery but the subscription outcome has already changed.
Subscription state decides whether action is appropriate; the channel layer decides how that approved action is delivered.
5. Operate the pipeline with visible failure states
Track accepted, processed, skipped, retried, and failed events as distinct outcomes. A skipped event should carry a reason such as duplicate delivery, stale transition, unsupported environment, or no eligible recovery case.
Alert on growing queues, repeated processing failures, and unusual drops in event volume. The recovery team should be able to answer whether the system is quiet because customers are healthy or because the pipeline stopped moving.
- Processing latency from receipt to state update
- Retry count and oldest unprocessed event
- Cases opened, closed, or suppressed by event type
- Failures grouped by actionable reason
The operating takeaway
Turn the framework into one measurable action.
Treat RevenueCat webhooks as inputs to a durable subscription-state system. Reliable ingestion, idempotent processing, current-state resolution, and observable failure handling make recovery automation safe enough to trust.
Continue learning