Implement webhook idempotency and retry handling for accounting integrations

In-depth guide

Steps

1. Assign or extract a stable unique identifier for each webhook event (many platforms provide an event ID in the payload or headers); store processed event IDs in a durable datastore.
2. Before processing any incoming webhook event, check whether the event ID has already been recorded in your idempotency store; if it has, return HTTP 200 immediately without reprocessing.
3. Respond to the webhook delivery with HTTP 200 as quickly as possible (ideally under a few seconds); offload actual processing to an async queue to avoid timeouts that would trigger source retries.
4. Design all processing logic to be safe to run multiple times with the same input (idempotent operations): use upsert semantics rather than blind inserts, and verify current resource state before applying updates.
5. Implement your own retry logic for downstream API calls (to the accounting platform) with exponential back-off and a maximum retry count; log failures with enough context to support manual reconciliation.
6. Set an expiry TTL on idempotency store entries (e.g., 30 days) to bound storage growth; most webhook platforms will not retry events indefinitely beyond their own retry window.