RevOps Playbook: Sync Best Practices, Errors, and Deduplication for HubSpot–Salesforce

Q: What is the single best duplicate prevention step?

Validate email and company domain at the point of capture, and check against existing Leads and Contacts before creating anything. Favor conversion over new creation in Salesforce.

Q: How do we stop bidirectional “ping‑pong” updates?

Reduce bidirectional fields to the bare minimum, enforce normalization, and add a cooldown (e.g., ignore updates from the other system for 10 minutes after you write).

Q: Should we let enrichment overwrite names and titles?

No. Write enrichment to shadow fields and promote only when a confidence threshold is reached and a human hasn’t edited the canonical field recently.

Q: How do we handle transient API failures?

Retry with exponential backoff and jitter, cap retries, and ensure idempotency so repeated attempts don’t create duplicates or regress fields.

Q: What does good observability look like?

Record‑level logs with correlation IDs, error taxonomies with top offenders, backlog depth/age, and daily reconciliation against a short list of canonical counts.

Published by Bles Software, a custom software and AI company based in Yehud-Monoson, Israel, building web apps, AI agents and API integrations for clients in Israel, the US, the UK and the EU.

Why This Matters

The fastest way to lose go‑to‑market confidence is a noisy, brittle sync. This playbook focuses on the mechanics that keep your HubSpot–Salesforce connector healthy: sync design patterns, error prevention, duplicate control, and incident response. Treat the integration as production software with SLOs and a runbook, not an admin checkbox.

Design Goals

Predictable, explainable sync behavior that users can trust.
Minimal bidirectional fields and no oscillation.
Observability: logs, metrics, and alerts that point to root cause.
Resilient to volume spikes and vendor rate limits.

Sync Patterns That Scale

Guarded bidirectional fields: allow both systems to edit only when values are normalized and rules (e.g., last‑updated wins with cooldown windows) prevent ping‑pong.
Write‑once fields: stamp originating values (e.g., first_touch_channel, original_source) and never overwrite.
Staged backfills: bulk loads in batches with backoff; disable real‑time triggers during large migrations.
Priority queues: route owner, stage, and lifecycle updates first; schedule low‑risk properties later.
Partial failure isolation: design idempotent retries keyed by record IDs to avoid duplicates on retriable errors.

Error Taxonomy

Group errors by what you can act on quickly:

Authentication/authorization: expired tokens, permission mismatches, IP restrictions.
Schema: missing fields, invalid picklist values, length and format violations.
Identity: duplicate key errors, missing foreign keys, disallowed create paths.
Rate limits: 429s and concurrency failures.
Transient network: timeouts and 5xx.

Preventing Errors

Principle of least privilege: integration users need only the scopes they truly require; over‑wide privileges hide schema mistakes.
Validation at source: enforce ISO country/state, E.164 phone, email format, and picklists in forms; bad data should not enter the sync.
Controlled picklists: align option sets and case; disable free‑text anywhere that feeds the sync.
Change control: any field or picklist change goes through PR + UAT to catch breaking changes.

Handling Rate Limits

Exponential backoff with jitter; cap retry count per record to avoid storms.
Queue with priorities; pause low‑value updates during spikes.
Batch when possible; compress field updates for the same record into a single write.

Duplicate Prevention and Cleanup

Dupes are inevitable without explicit controls.

Creation gates: before creating in either system, check by email (Contacts) and domain (Companies/Accounts). For Salesforce Leads, also check Contact by email to prefer convert over create.
Suppression windows: if a record was created in one system within the last X minutes, avoid creating the “mirror” until the first record syncs back.
Merge policy: centralize merges in Salesforce for Accounts/Contacts and mirror to HubSpot; keep HubSpot as a consumer for merges to prevent divergence.
Role‑based emails: block generic inboxes (info@, support@) from auto‑creation; route to a review queue.

Incident Response and Runbook

SLOs: <1% sync error rate, <5 minutes mean time to detect, <2 hours mean time to resolve for P1. Runbook:

Detect: alert triggers on error rate/backlog threshold.
Contain: pause noncritical jobs; notify stakeholders.
Diagnose: classify error; inspect last deploys and schema changes; sample failed payloads.
Resolve: hotfix config or rollback; requeue failed records idempotently.
Learn: post‑incident review; add test/alert to prevent recurrence.

Logging and Metrics

Per‑record correlation IDs and operation type (create, update, convert, merge).
Error breakdown by taxonomy; top fields causing failures; top picklist violations.
Backlog depth and age; moving averages for throughput and latency.
Daily reconciliation counts for MQL, SAL, SQL, Closed Won.

Safe Backfills and Migrations

Freeze rules: temporarily lock write‑once fields to prevent accidental overwrites.
Snapshot: export pre‑backfill counts and a sample of records; compare after.
Phased rollout: start with a small cohort, then scale; keep a kill switch.

UAT Scenarios to Prove Stability

Bidirectional edit without oscillation on Title/Phone.
Lead conversion path (Lead → Contact + Account) with sync continuity.
Owner change propagation with SLA timers preserved.
Large import with validation errors captured and quarantined.

People and Process

RACI: RevOps owns runbook and SLOs; Admins own platform configuration; Data owns reconciliation and anomaly detection.
Change windows: restrict risky releases to low‑traffic times; staff on‑call.

Common Pitfalls

“Sync everything” mindset; it increases conflicts and floods logs.
Suppressing errors instead of fixing root causes.
Letting enrichment overwrite human‑verified values.
No quarantine—bad data slips into both systems and doubles cleanup effort.

Checklist Before Production Cutover

Field dictionary and ownership published.
Alerts configured and tested (auth, rate limit, backlog, schema errors).
UAT passed on identity, routing, lifecycle, and opportunity sync.
Backfill plan and rollback plan documented.

FAQ

What is the single best duplicate prevention step?