The decision
Use a resumable initial import, incremental change processing and periodic reconciliation. Webhooks shorten the delay; they do not remove the need to recover missed or duplicated changes.
Make the first import resumable
Partition work by customer, connected company and resource. Persist a checkpoint after a batch is durably stored, and give every imported record a key that includes its provider company. Separate the source record version from your processing timestamp.
Test an import that stops halfway through a page and starts again. It should neither skip records nor duplicate them. A large customer must not block smaller customers behind one unbounded queue; assign work in bounded batches with independent progress.
Use notifications as triggers, not the ledger
Intuit recommends compensating for missed webhooks with Change Data Capture and processing notifications asynchronously. Its configuration documentation also describes a CloudEvents payload and company identifiers. Implement against the documented payload version rather than copying an old webhook example.
A practical design validates the notification, stores enough information to retry, acknowledges it promptly and schedules the relevant source read. Do not let a slow reporting query delay acknowledgement. Scope the queue item to the authorized company.
Reconcile business meaning as well as record counts
Compare a bounded set of source records against your projection: updated invoices, voids, deletions and balances. The recovery mechanism depends on the provider; do not assume another API has QuickBooks CDC semantics. Record discrepancies and the source checkpoint that produced them.
For financial reporting, equal row counts do not establish correctness. Check totals and status transitions using the provider’s definitions, preserving currency and source precision rather than converting everything to a floating-point approximation.
Give users a truthful sync status
Expose last successful sync, current backlog and a recoverable error state. Distinguish expired authorization from a transient provider outage. A retry policy should respect provider limits and stop retrying permanent validation errors.
Before launch, simulate duplicate events, out-of-order updates, an expired token and an interrupted backfill. Your runbook should identify the affected company, replay a bounded range and explain how you will verify recovery without rerunning every customer.
Your next step
Use these checks in a bounded proof of integration.
- Persist durable per-company checkpoints.
- Test duplicates, ordering and interrupted pagination.
- Reconcile source totals and deletion behavior.
- Show freshness and actionable connection errors.
Profiles to inspect: QuickBooks · Xero · NetSuite
Sources and editorial scope
Product statements refer to the publisher sources below, reviewed on 2026-10-21. The decision criteria and checklists are API Tracker’s editorial analysis. They are not compatibility certifications or benchmark results. API Tracker is built by Apideck.
Suggest a correction →