Build a dependable synchronisation
A reliable integration combines a repeatable initial load, a process for updates, and a way to recover when something is missed.
Initial load
Read a supported collection in a stable order, process a bounded batch, and persist its checkpoint only after the target system accepts it. For resources that support it, sort=id with filter=greaterThan(id,'...') avoids repeatedly requesting deeper numbered pages.
This is traversal by ID, not a point-in-time snapshot. New records, edits and access changes can occur while you are reading. Avoid assuming that finishing a traversal proves both systems are identical.
Ongoing changes
Use configured webhooks for timely notifications. Where a resource exposes a filterable update timestamp, a periodic query with an overlap window can help find late or retried changes. Verify the field and timestamp semantics for that resource first; there is no universal change-feed or cursor contract implied here.
Store the last successfully processed position and make local upserts repeatable. Record which system owns each writable field to prevent update loops.
Reconciliation
Schedule periodic comparisons to recover missed notifications or failed processing. Account for deletions, records leaving your access scope and downstream failures. A 404 alone does not prove deletion; it can also reflect visibility or an incorrect identifier.
For a webhook, retrieve the current authorised record where appropriate. A notification may describe an earlier change than the record's current state.
Retry according to the operation
| Situation | Response |
|---|---|
| Expired token on a safe read | Refresh once and retry if appropriate |
429 | Delay, back off and lower concurrency or cost |
| Transient failure on a read | Retry within a bounded policy |
| Timeout during a create | Reconcile before repeating; the write may have succeeded |
400 / 403 | Fix the request or access rather than repeating it |
Beta 423 | Check user context and arrange enablement before retrying |
External references are useful for correlation. They are not a documented general idempotency-key mechanism. Keep enough application-side state to investigate ambiguous results.
Follow the external integrations and references walkthrough to register an external system, link contacts and deals, and use the external-reference fields during lead creation.