Webhook Architecture for RevenueCat: A Backend Sync That Doesn’t Silently Drift

A webhook handler that works in every manual test and then quietly drifts out of sync in production is one of the more common failure modes we see in subscription backends — not because the code is wrong exactly, but because it was written for the happy path and webhooks don’t reliably stay on it. This is the pattern we default to, built around three specific failure modes rather than general best-practice advice.

1. The Three Failure Modes This Is Built Around

2. The Pattern

The receiver’s only job is to verify the request is genuinely from RevenueCat, hand the event to a durable queue, and return success immediately — not to do the actual entitlement-sync work inline. This matters because RevenueCat (like most webhook senders) will retry a delivery that doesn’t get a fast success response, which is exactly the mechanism that produces duplicates if your handler is slow or flaky.

The worker that actually processes events off the queue does three things every time: checks whether it has already processed this specific event ID (idempotency), applies the entitlement change only if the event’s timestamp is newer than the last applied change for that subscriber (ordering), and lets the queue’s own retry mechanism handle transient failures rather than the webhook sender’s retry mechanism.

This general pattern is the missing piece underneath two things we’ve covered elsewhere: it’s what makes the analytics pipeline in our RevenueCat analytics piece trustworthy rather than approximately correct, and it’s the exact discipline that matters most during the dual-write validation window in our iOS migration playbook.