RevOps Playbook: HubSpot ↔ Salesforce Integration Setup and Governance

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.

Modern revenue operations relies on a single, trusted view of the customer journey. When HubSpot and Salesforce are integrated well, marketing’s engagement data and sales’ opportunity truth reinforce one another, accelerating lead velocity, boosting conversion, and improving forecast accuracy. When the connection is fragile or misconfigured, the opposite happens: duplicated records, broken attribution, and stalled processes. This playbook gives RevOps teams a pragmatic, step‑by‑step approach to stand up, harden, and govern a HubSpot ↔ Salesforce integration designed for scale.

What a Great Integration Unlocks

A durable integration isn’t just “data is syncing.” It’s a system that produces consistent, decision‑ready signals with clear ownership and failure modes. Done well, you will:

Reduce lead routing errors and handoff delays across lifecycle stages.
Align campaign performance and revenue outcomes for trustworthy attribution.
Eliminate conflicting sources of truth for contact, company, and opportunity data.
Shorten sales cycle time with complete activity context and up‑to‑date intent.

Behind each outcome is a set of design choices—what syncs, when, in which direction, and with what controls. The rest of this playbook focuses on those decisions and the governance that keeps them reliable.

Prerequisites and Environment

Before you install anything, confirm foundational readiness:

A dedicated Salesforce user reserved for the integration (details below).
A sandbox or staging Salesforce org with representative metadata and test data.
HubSpot Professional/Enterprise tier with API access and required integration limits.
A source of truth for field definitions (a living data dictionary) and a naming standard.
Agreement across Marketing, Sales, and RevOps on lifecycle definitions (Lead, MQL, SQL/SAO, Opportunity) and allowed state transitions.

Document these prerequisites in a shared repository. Treat this document as the contract that the integration must uphold in configuration and testing.

Establish the Integration User in Salesforce

Create a unique, non‑human Salesforce user licensed and profiled only for the data it needs. This prevents permission drift and provides a clean audit trail.

Create a profile or permission set with read/write on Leads, Contacts, Accounts, Opportunities, Campaigns, Campaign Members, and Tasks (as required for your program).
Grant API Enabled, Modify All Data only if required for initial mapping, and the minimum system permissions necessary for field‑level operations.
Restrict visibility with role hierarchy and sharing rules so the user can only access the records the business intends to sync.
Disable login from non‑integration networks (via login IP ranges if your policy requires it). Rotate the password on a regular cadence and store secrets in a vault.

In HubSpot, plan to authorize the Salesforce app with an admin who can delegate access cleanly to the integration user’s context.

Install, Connect, and Authenticate

The installation itself is simple; the decisions you make during setup are not. Use sandbox first.

In sandbox, install the HubSpot–Salesforce integration. Authenticate using a Salesforce admin, then confirm the connection impersonates the integration user for data actions.
Pause automatic full sync options during installation. You’ll turn on sync selectively after mapping and tests.
Enable error logging and notifications to a shared RevOps email or Slack channel so the team sees failures quickly.

Once connected, export the initial integration configuration (HubSpot sync settings JSON where available, screenshots otherwise) into your repo. Treat this as infrastructure documentation.

Define Directionality and Conflict Rules

Every major object should explicitly state directionality and conflict handling.

Contacts/Leads: Most teams choose bi‑directional sync for core identity and routing fields, with Salesforce as the final authority for sales‑owned states (e.g., Lead Status, Lifecycle Stage transitions beyond SQL/SAO). Marketing‑owned behavioral fields often remain HubSpot‑source‑of‑truth.
Accounts/Companies: Many teams use Salesforce as the company authority, enriching to HubSpot. Decide if HubSpot Companies can create Accounts or only link to existing Accounts.
Opportunities/Deals: If Sales forecasts in Salesforce, treat Opportunities as read‑only in HubSpot or create read‑only mirror Deals for reporting. If Deals are edited in HubSpot, ensure one‑way rules prevent accidental overwrites.
Campaigns and Campaign Members: Prefer Salesforce Campaign Member status as the canonical engagement state when attribution must tie to Opportunities; ensure HubSpot Campaigns are mapped or mirrored consistently.

When conflicts occur (both sides changed recently), choose a deterministic winner per field. Document these rules in the data dictionary.

Field Mapping and Minimal Viable Schema

Fight the temptation to sync everything. A minimal viable schema keeps the system fast, traceable, and easier to govern.

Identity: Email, Record ID(s), Company Domain, and a stable Account key. Add second‑order identity (Phone, LinkedIn URL) only if your dedupe rules use them.
Routing and Ownership: Lead Status, Lifecycle Stage, MQL Reason, Owner, Queue, Territory.
Qualification: Job Title, Persona, ICP Fit, Source/Medium/Campaign, Campaign Member Status.
Commercial Context: Segment, Vertical, ARR Band, Buying Role, Intent Signals.

For each mapped field, define:

Purpose and business question it answers.
Owning system and directionality.
Allowed values and validation rules.
Conflict winner and default behavior on null or invalid values.

Your data dictionary is the guardrail. When a new field is proposed, it must pass a purpose test and a governance review.

Inclusion Lists, Volume Controls, and Sync Filters

Full‑database synchronization is rarely necessary and often harmful. Create narrow inclusion criteria that evolve with the program.

Contacts: Start with opted‑in marketable contacts and active customers. Exclude obvious system noise (test domains, internal emails), competitors, and one‑time event registrants if not part of your motion.
Companies/Accounts: Include only ICP segments or accounts with open opportunities. Avoid back‑filling low‑value legacy records.
Campaign Members: Mirror only programs tied to pipeline goals, not every email or nurture touch.

Filters reduce load, avoid rate limits, and contain the blast radius of mapping mistakes.

Lifecycle and State Transitions

Agree on a single canonical lifecycle. Most teams use HubSpot Lifecycle Stage up to MQL and Salesforce Lead Status and Opportunity Stage after sales acceptance.

Marketing Ownership: Anonymous → Subscriber → Lead → MQL. HubSpot owns scoring, intent, and enrichment to promote to MQL.
Sales Ownership: SQL/SAO → Opportunity stages. Salesforce owns acceptance, disqualification reasons, and progression.
Guardrails: Prevent regressions (e.g., SQL back to Lead) unless explicitly allowed with a reason code.

Record every state change with timestamp and actor so RevOps can audit how a record moved through the funnel.

Sandbox‑First, Change Control, and Release Management

Treat the integration like product infrastructure.

Work in a sandbox with representative fields and picklists. Mirror mappings and inclusion lists.
Version mappings: store a dated mapping matrix in your repo. Each release modifies the matrix and includes a migration note.
Use change checklists: pre‑deploy validation, post‑deploy smoke tests, and rollback steps.
Batch changes: bundle multiple field updates into scheduled windows rather than continual tweaks.

A disciplined release process prevents mid‑campaign surprises and keeps the data warehouse stable.

Error Handling, Monitoring, and Alerting

Failures happen. Design for fast detection and clear ownership.

Enable integration error dashboards in HubSpot and Salesforce. Subscribe a RevOps distribution list for alerts.
Classify errors into categories: permissions, validation/picklist mismatches, missing parent records, API limits, and network/transient.
For each category, pre‑define runbooks: reproduce, fix, backfill, and verify.
Track mean time to detect (MTTD) and mean time to repair (MTTR) as operational KPIs.

When a backfill is needed, use narrow date windows and inclusion filters to avoid overwhelming the systems.

Data Retention, Privacy, and Compliance

Sync only what you need and protect it.

Minimize PII fields flowing to both systems. If only Salesforce requires a national ID or other sensitive field, do not map it to HubSpot.
Respect consent flags and regional requirements. If a contact opts out in HubSpot, ensure the unsubscribe state propagates and is honored downstream.
Set retention/archival policies for inactive contacts and closed opportunities. Fewer rows mean faster reporting and fewer surprises.

Security reviews should be part of integration releases—not an afterthought.

Cutover and First 30 Days

A careful cutover reduces noise and builds confidence.

Run a dry‑run sync in sandbox with a small, labeled cohort. Validate field values, state transitions, and ownership rules.
In production, enable sync in phases: Contacts first, then Companies/Accounts, then Campaign Members, and finally optional Deals/Opportunities mirroring if used.
Monitor errors daily, publish a “known issues” page, and hold a weekly RevOps standup focused on the integration.
Share a simple enablement guide for go‑to‑market teams explaining what changed and how to request updates.

By day 30 you should have baseline MTTD/MTTR metrics, stable error volume, and stakeholder confidence.

Ongoing Governance and KPIs

Integration health is measured by outcomes and by the absence of surprises. Track:

Lead velocity and conversion at each lifecycle transition.
Duplicate creation rate per 1,000 net new records.
Sync error rate and time to remediation.
Attribution coverage: percentage of Opportunities with Campaign influence.

Establish a quarterly review where Marketing, Sales, and RevOps evaluate schema additions, field usage, and backlog requests. If a field or rule isn’t used to make decisions, remove it.

FAQ

Do we need both Leads and Contacts in Salesforce if HubSpot manages Lifecycle?

Often yes. Leads support pre‑conversion routing and assignment, while Contacts represent known people tied to Accounts. If you use a lead conversion process, make sure the integration reflects the new Contact and Opportunity relationships without creating duplicates or losing campaign history.

Should Opportunities sync to HubSpot or stay in Salesforce only?

If Salesforce is the forecasting system, prefer one‑way sharing of Opportunity data to HubSpot for reporting and segmentation. Two‑way editing is possible but risky; it increases conflict potential and complicates governance. If you enable HubSpot Deals, make them read‑only mirrors or ensure strict field guardianship.

What’s the best way to prevent duplicates between systems?

Use deterministic rules first (email, company domain) and narrow inclusion lists so you only sync qualified records. Employ Salesforce duplicate rules and HubSpot duplicate management together. When in doubt, block creation and route to a queue for RevOps review rather than letting a near‑duplicate through.

How do we handle picklist mismatches and validation rules?

Inventory all mapped picklists, align allowed values, and add translation rules in HubSpot where appropriate. For validation rules in Salesforce, either meet them in HubSpot before sync or create dedicated bypass exceptions for the integration user—documented and time‑boxed.

Can we rely on Campaign Member Status for attribution?

Yes, if you adopt Salesforce Campaign hierarchy and standardize statuses per tactic. Map HubSpot Campaigns and Membership carefully. Ensure that Campaign association occurs before or at the moment an Opportunity is created to capture influence.

How do we roll back a bad mapping change?

Keep mappings under version control. If an error deploys, revert to the prior version, disable the offending sync, and backfill only the affected fields over a short time window. Update the runbook with the root cause and the specific guardrail that will prevent recurrence.

What KPIs show that integration governance is working?

Stable or improving lead‑to‑MQL and MQL‑to‑SQL conversion rates, a low duplicate rate, fast error remediation, and consistent attribution coverage. Qualitatively, fewer “why did this record change?” tickets from go‑to‑market teams is a strong signal.