Webhooks are notification, not perfect synchronization A payment provider can retry, delay, or reorder events. Your application can also be unavailable whe...
Webhooks are notification, not perfect synchronization
A payment provider can retry, delay, or reorder events. Your application can also be unavailable when an event arrives. A reconciliation process compares local subscription or order state with the provider's authoritative records and repairs differences under controlled rules.
Start by storing every verified provider event ID and processing result. A unique constraint prevents duplicate application of the same event. The event handler should update local state only after checking that the transition is valid for the current object and event version.
Define the comparison set
Reconcile objects changed recently, objects with failed event processing, and objects with an uncertain local state. Fetch provider data through its supported API with pagination and rate limits. Compare identity, status, amount, currency, period dates, and relevant refunds. Avoid overwriting a local exception simply because one field differs.
Classify mismatches
Some differences are expected while a payment is pending. Others require intervention: local access active after provider cancellation, a paid provider invoice without local entitlement, or a captured order with no fulfillment record. Give each mismatch a code, severity, and safe repair action.
For a financial adjustment, preserve the original event and create a correction record. Silent mutation of historical amounts makes later audits difficult.
Design a controlled repair
The repair job should be idempotent and log its decision. Some discrepancies can be fixed automatically, such as refreshing a stale period end; others need a human to inspect refunds or chargebacks. A support screen should show the local and provider states side by side without exposing secrets.
Test outage scenarios
Disable the webhook endpoint in a test environment, generate provider events, restore the endpoint, and run reconciliation. Test duplicate and out of order events, provider rate limiting, and a repair that fails halfway through. Confirm the system eventually converges without issuing duplicate refunds or notifications.
Conclusion
Reconciliation is the recovery path for imperfect event delivery. Pair it with verified, idempotent webhooks and clear exception review. The web and SaaS development service includes subscription and payment workflows.
References