HubSpot–Salesforce Two‑Way Sync Troubleshooting and Data Hygiene Playbook

Two‑way sync can be a superpower or a source of chaos. The difference is hygiene: explicit ownership, deterministic error handling, and routine cleanup. This playbook gives RevOps a pragmatic, step‑by‑step method to diagnose sync failures, prevent regressions, and institutionalize data hygiene across HubSpot and Salesforce.

Why Two‑Way Sync Breaks

Two‑way sync fails for a small set of predictable reasons: field mismatches, ownership collisions, picklist drift, duplicate keys, and workflow loops. Understanding these failure modes—and the logs where they surface—turns unpredictable escalations into a short checklist your team can run on autopilot.

Common Failure Modes

Field type mismatches (e.g., HubSpot text vs. Salesforce picklist) cause write rejections.
Ownership edits from HubSpot collide with Salesforce assignment rules and validation.
Picklist values diverge over time as teams add local options.
Duplicate keys (same email/domain) lead to merges failing or activities attaching to the wrong record.
Automation loops occur when workflows react to each other’s updates without guardrails.

The Golden Runbook

Use this runbook whenever an issue arises. The guiding principle is to work from the platform logs outward, validate assumptions on a test record, then address the root cause in configuration—not ad‑hoc record edits.

Step 1: Identify the Symptom and Scope

Gather the basics: which object (Contact, Company/Account, Deal/Opportunity), which field(s), unilateral or bilateral direction, and whether failures are isolated or systemic. Pull a recent failing record ID from the error queue.

Step 2: Check Integration Logs

In HubSpot, review the Salesforce integration logs for the record. In Salesforce, check the Debug Logs for the integration user and any validation errors. Capture the exact error string; it is usually precise (e.g., “invalid picklist value: Tier—Enterprise”).

Step 3: Reproduce on a Test Record

Clone the failing record into a disposable test record in both systems. Apply the same field change and watch the logs. If reproduction fails, the original issue was transient (e.g., API limits) or tied to data on that specific record.

Step 4: Determine Ownership and Precedence

Confirm the source of truth for the field. If Salesforce owns it, block HubSpot workflows from setting it. If HubSpot owns it, ensure Salesforce validation rules allow the integration user to write the value or that transformation is applied first.

Step 5: Map, Transform, or Normalize

Fix the mismatch at the configuration layer: align field types, map picklist values with a transformation table, normalize strings (trim whitespace, consistent casing), and convert data types where needed.

Step 6: Release, Monitor, and Document

Deploy the config change in a change window. Monitor the error queue for 48 hours. Write a post‑mortem that documents the root cause, the change, and how to detect the issue earlier next time.

Data Hygiene Principles for RevOps

Hygiene is a weekly habit, not a quarterly project. The highest‑performing teams have small, boring routines that compound into reliability.

Ownership Discipline

Assign a single owner per field. Encode ownership in the mapping catalog with a clear direction (Salesforce → HubSpot, HubSpot → Salesforce, or bi‑directional) and a tiebreaker policy. Protect sales‑critical fields with validation rules and restrict HubSpot workflows from modifying them.

Picklist Governance

Create a dictionary of allowed values with human‑readable display names and machine‑readable keys. For example, use “enterprise” as the key everywhere and display “Enterprise” in UI. When teams request a new value, update both systems and the transformation table in the integration.

Identity and De‑Duplication

HubSpot uses email as the primary key; Salesforce can also use email for Leads and Contacts but often relies on IDs and account hierarchies. Maintain cross‑refs: store Salesforce IDs in HubSpot and vice versa. For de‑duplication, start deterministically, then layer fuzzy logic: name normalization + domain + recent activity overlap.

Opt‑in and Consent

HubSpot should remain authoritative for subscription types and email opt‑out to respect consent centers and auto‑suppression. Salesforce surfaces the consent state for visibility. Never flip opt‑out in Salesforce via automation; rely on HubSpot’s mechanisms.

Monitoring and Alerting

Two dashboards keep your integration healthy: an error queue and a data quality scorecard. The error queue tells you what broke today; the scorecard tells you what will break tomorrow.

Error Queue

Track counts by object, field, and root cause. Aim for short time to triage (daily during hypercare, weekly afterwards). Review trends: recurring picklist errors indicate taxonomy drift; repeated owner write failures indicate permission regressions.

Data Quality Scorecard

Define leading indicators: duplicate rate by object, % records missing core fields (industry, segment), % invalid picklist values, and number of unmapped fields. Track conversion rates across lifecycle stages to detect silent breakage.

Cleaning Procedures That Actually Stick

Avoid heroic cleanups that collapse in a month. Instead, implement procedures with automation and guardrails.

De‑Duping Contacts and Companies

Start with deterministic merges: exact email for Contacts; exact domain for Companies. Then review fuzzy candidates weekly with a RevOps + SDR pairing. Automate post‑merge tasks: re‑associate activities, re‑enroll in nurture, and notify the owner.

Picklist Normalization

Add a transformation layer that maps synonyms (e.g., “mfg” → “manufacturing”). Write back the normalized value to the system of record and log exceptions for manual review.

Lifecycle Corrections

Occasionally records advance out of order. Create a “Lifecycle Correction” workflow that flags contradictions (e.g., SQL without SAL) and routes them to RevOps for guided fixes. Never bulk‑regress lifecycle automatically.

Preventing Workflow Loops

Loops arise when a change in one system triggers an update in the other, which triggers the first again. Break loops with one or more of these tactics:

Add idempotency keys (e.g., if the last change was made by the integration user within five minutes, ignore).
Write to staging fields first and promote to final fields only after validation.
Separate human‑authored updates from machine‑authored updates with field history and audit filters.

Rollout Pattern for Risk Reduction

Roll out two‑way sync in stages and with a canary cohort so issues are localized and reversible.

Pilot Cohort

Choose one business unit, 10 accounts, and 100 contacts. Give their owners advance notice. Turn on two‑way sync for non‑destructive fields only. Meet daily during the first week to review logs and user feedback.

Expansion Gates

Set gates for each expansion: 95% error‑free sync for a week, zero duplicate spikes, and no unresolved owner collisions. Document every gate pass in a change log.

Weekly Hygiene Cadence

Keep the cadence short and boring, and you will keep the data clean.

Triage integration errors and close or route with owners.
Review new picklist values and update the dictionary + mappings.
De‑dupe the top 50 fuzzy matches and cascade merges.
Spot‑check lifecycle transitions and reconcile attribution deltas.

Training and Enablement

Technology alone cannot prevent chaos; users need clear behavior expectations and a simple way to ask for help.

Work the Record, Not the System

Show SDRs and AEs exactly which fields to update in Salesforce and which behaviors in HubSpot will auto‑populate those fields. Provide a one‑pager on “What changes are blocked and why” so users understand owner and lifecycle guardrails.

Escalation Paths

Document how to escalate a broken record, including the exact details needed by RevOps (record IDs, timestamps, expected vs. actual). Publish a service‑level objective (SLO) for response and resolution, and report on adherence.

FAQ

What error should I fix first when the queue fills up?

Prioritize errors that block handoffs or change ownership because they have the largest downstream impact. Fix picklist mapping errors next because they produce silent misreporting. Defer low‑impact cosmetic mismatches until the weekly review.

How do we prevent users from making changes in the wrong system?

Use validation rules in Salesforce to block edits on sales‑owned fields from any user except the integration user where appropriate, and restrict HubSpot workflows from setting those fields. Train users on the correct place to make each edit.

What’s the best approach to duplicate cleanup without disrupting reps?

Start deterministic, then schedule weekly fuzzy reviews with SDRs who know the accounts. After merges, automatically re‑associate activities and notify the owner so they do not lose context or tasks.

Why do my UTMs look fine in HubSpot but not in Salesforce?

Likely because Campaign naming or a crosswalk is missing. Standardize UTM keys, enforce a shared link builder, and either mirror Primary Campaign Source from Salesforce to HubSpot or maintain a crosswalk so both systems speak the same language.

Can we trust two‑way sync for owner and status?

Yes, but only if Salesforce remains authoritative for owner and status and HubSpot is read‑only for those fields. Allow HubSpot to request routing (via a staging field) and let Salesforce finalize the owner.

When should we pause workflows during cleanup?

Pause workflows before large imports, schema changes, or lifecycle backfills. After the change, re‑enroll only the subset that actually requires automation, and document the action in your change log.