RevOps Playbook: Troubleshooting, Monitoring, and Governance for HubSpot–Salesforce Sync

Integrations don’t break; they drift. A field changes picklist values, a new workflow collides with an old rule, an API token expires. This playbook gives you a repeatable operating model to troubleshoot quickly, monitor proactively, and govern the HubSpot–Salesforce integration so it remains boringly reliable.

Incident Response Basics

When an integration incident hits, time and clarity matter more than heroics. Adopt a lightweight incident routine:

Declare severity and scope (object, systems, time window). Communicate impact plainly.
Freeze non‑essential changes. Pause deploys and experimental workflows until resolution.
Triage by failure type: transient (rate limits, timeouts) vs data (validation errors, missing fields).

A Structured Troubleshooting Flow

Reproduce with a single record. Identify the exact property or operation failing.
Check recent changes: property additions, picklist edits, workflow publishes, permission changes.
Inspect logs and last sync status fields; note error codes and timestamps.
Attempt minimal, reversible fixes first—retries, value normalization, or a targeted workflow pause.
Document the root cause and the change that prevented recurrence.

Monitoring That Catches Problems Early

Health metrics: daily success rate by object, average retry count, top error reasons.
Canary tests: create a test Contact in HubSpot, verify Salesforce creation, convert to Opportunity, confirm HubSpot deal mirroring.
Threshold alerts: spike detection on errors and sudden drops in created/updated records.

Logging and Observability

Write a compact log per sync attempt: record ID, operation, result, error reason, and source system.
Summarize into dashboards with daily/weekly rollups to spot trends.
Keep logs for at least 90 days to investigate delayed symptoms.

Governance: Rules of the Road

Governance prevents accidental change from causing unplanned outcomes.

Field Contract: owner, direction, allowed values, transformation notes. Required for every mapped property.
Change management: planned release windows, sandbox validation, and smoke tests.
Security: dedicated integration users with least privilege and quarterly token rotation.

Backfills and Reprocessing

Occasionally you must backfill missing values or replay failures.

Idempotent design: use external IDs so reprocessing doesn’t create duplicates.
Batches with checkpoints: process records in small chunks; log progress and continue on failure.
Post‑backfill verification: sample reports showing expected field distributions and counts.

Common Failure Patterns (and Fixes)

Picklist mismatches: normalize values or update the receiving picklist. Add a “quarantine” value to capture unknowns without blocking syncs.
Null constraints: set sensible defaults or compute values upstream before send.
Permission errors: verify the integration user’s profile and field‑level security; avoid recently added custom fields without access.
Rate limits: implement exponential backoff and distributed scheduling to smooth peaks.

Operational Runbook

Daily: scan error dashboards, review canary flow, triage new failures.
Weekly: trend top error reasons, review exceptions, and close the biggest source of repeat issues.
Monthly: reconciliation between HubSpot and Salesforce on lifecycle counts and revenue; renew tokens set to expire within 60 days.

Incident Postmortems That Actually Help

Timeline: what happened and when, including detection and response times.
Impact: records affected, systems, and visible business impact.
Root cause: technical and organizational factors.
Fixes: immediate remedial actions and durable prevention changes (tests, contracts, alerts).

Keep postmortems blameless and focused on learning; publish them in a shared repo for reference.

FAQ

How do we distinguish systemic failures from one‑off data issues?

Look for clustering: same error reason across many records or a spike in a time window suggests a systemic issue. One‑off errors are usually validation misses or data entry mistakes.

What’s the minimum logging to be useful?

Record ID, operation, outcome, error reason, and timestamp. With that, you can group by error reason and trend over time to pick targets for fixes.

How can we avoid noisy alerts?

Alert on rate of change rather than absolute counts, and include a minimum window (e.g., five minutes) to avoid transient flaps. Always include a link to the runbook.

How do we manage integration credentials safely?

Use dedicated users, vault secrets, and rotate tokens quarterly. Trigger alerts on authentication failures and revoke unused credentials after a grace period.

When should we pause the sync?

When data corruption risk outweighs delay, such as a widespread mapping error or runaway workflow loop. Communicate early, fix fast, then replay safely with idempotent keys.