HubSpot–Salesforce Sync Health and Deduplication Playbook

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.

If mapping is the blueprint, then sync health is the telemetry that keeps the HubSpot–Salesforce connection on the rails. This playbook shows how to instrument your integration, detect and resolve errors quickly, prevent duplicates at the source, and keep reporting consistent when data volume or process changes spike. Use it as your operational runbook for day‑to‑day reliability and incident response.

Objectives

Build a system that is observable, self‑healing where possible, and fast to recover when humans must intervene. Your top objectives:

Detect failures before downstream leaders feel them in reports.
Prevent duplicate Contacts/Companies/Deals at creation, not weeks later.
Contain sync loops and noisy workflows that thrash records.
Maintain funnel parity (MQL, SAL, SQL, Opps) within 3% across systems.

Telemetry Model: What to Measure

Create a standard telemetry schema. Track counts and latencies for: created/updated records, error buckets (validation, permission, API limits, unknown picklists), queue depth, and processing latency between write and successful sync. Keep 30–90 days of history for trend analysis.

Golden KPIs

• Error rate <1% of sync attempts, with daily trend. • 95th percentile latency under 5 minutes for create/update flows. • Duplicate rate <0.5% for Contacts and Companies over a rolling 30‑day window. • Funnel parity drift <3% for core stages and opportunity creation.

Error Taxonomy and Routing

Classify errors so they route to the right owner:

• Validation failures: picklist value not allowed, missing required field. Route to RevOps. • Permissions: field‑level security or profile issues. Route to Salesforce Admins. • API limits: burst throttling or daily cap. Route to Integration Owner with runbook to stagger jobs. • Referential integrity: missing parent (Account before Contact, Opportunity before Product). Route to Data Engineering/RevOps to backfill.

Each error class needs a documented remediation with examples and target resolution times.

Blocking Duplicates at the Source

Deduplication is cheapest at creation. Combine platform features and guardrails:

• Forms: prevent new Contacts when an email already exists; append activity instead. For high‑risk domains (e.g., personal email), require additional matching info or suppress creation. • Imports: run a pre‑import fuzzy match on email + name + company domain to mark potential duplicates; require operator review. • Integrations: before creating a Company from HubSpot, check Salesforce for Account domains and known aliases; resolve to an existing Account when confidence >0.9. • Sales assisted: use a Chrome extension or validation rule to block manual creation if a likely match exists.

Identity Keys and Merge Policy

Define canonical keys, then write them everywhere:

• Contacts: email (primary); Salesforce Contact ID mirrored in HubSpot. If contacts share email (rare), designate one master; suppress others from sync. • Companies: website domain (primary) plus Salesforce Account ID. Maintain a related list of additional domains in Salesforce and a lookup in HubSpot. • Deals/Opportunities: Salesforce Opportunity ID is the truth; HubSpot stores it and never rewrites post‑creation.

Merges should be logged with: master ID, losers, fields preserved, fields overwritten, and user who initiated. Keep a 90‑day audit.

Incident Response: From Alert to Resolution

Create a lightweight, repeatable cycle:

Alert fires (error rate spike, latency breach, parity drift >3%).
Triage dashboard opens with the latest error samples and top error codes.
Identify the change that triggered the incident (release, picklist change, campaign import).
Roll back the last change or apply a scoped block (disable a workflow, pause a sync job).
Repair data via targeted backfill or value translation; reprocess failed items.
Post‑mortem within 48 hours with lessons captured in the runbook.

Data Quality Automations

Automate checks and corrections that don’t require judgment:

• Normalize country, state, and industry values to master lists. • Backfill missing required fields for a specific segment (e.g., set Lead Source = “other” when unknown). • Enforce immutability on original source and first‑touch fields after the first write. • Use “Locked by Salesforce” flags to prevent HubSpot workflows from overwriting sales‑owned fields after SAL.

Guarding Against Sync Loops

Sync loops happen when both systems write the same field on update. Stop them with:

• One SoR per field and explicit write windows (HubSpot can write Lead Status only until SAL). • Conflict detection: if a field flips more than twice in 10 minutes, freeze writes and open an alert. • Change review: any workflow that writes mapped fields must include a ticket referencing the field ledger.

Testing and Sandboxes

Keep a representative sandbox with the integration enabled. Run weekly synthetic tests:

• Create a test contact journey (form fill → MQL → SAL → SQL) and validate every mapped field at each step. • Verify picklist translations and ensure invalid values are blocked early. • Confirm attribution fields are immutable after first write and survive merges.

Operating Cadence

Maintain a simple but firm rhythm:

Daily: review error dashboard and queue depth; remediate top 10 failures.
Weekly: reconcile funnel metrics and publish a parity diff; nudge owners on drift.
Monthly: duplicate review and merges; publish trend report; refresh runbook based on incidents.

Communications and Change Control

Create a dedicated Slack channel for integration alerts and triage. All changes to mapped fields, picklists, or workflows that touch mapped fields must go through a weekly RevOps change board. Include a short ADR, success criteria, and a rollback plan.

FAQ

How strict should duplicate blocking be on forms?

Bias to strict. Append activity to existing Contacts when email matches; if you must allow new creation, require a unique secondary key like phone and queue for review.

What’s the fastest way to reduce error volume after a picklist change?

Publish a translation layer that remaps incoming values to allowed ones, then clean up the source systems. Block unknown values at the edge going forward.

How do we resolve conflicting lifecycle values between systems?

Pick one system as system of record by phase. Let HubSpot promote up to MQL/SAL, then let Salesforce own SAL/SQL forward. Make downstream fields read‑only in the other system.

Should we run overnight batch sync or near‑real‑time?

Use near‑real‑time for lead routing and sales alerts; batch is fine for large enrichment updates. Keep latency under five minutes for sales‑critical updates.

What duplicates should we merge first?

Merge duplicates with revenue potential first: open opportunities, active customers, or high engagement. Then clean low‑risk duplicates in bulk under a scripted policy.