HubSpot Integration

How ImpactPilot Connects to HubSpot

Audience: Technical evaluators, HubSpot admins, and CSM leaders who want to understand what the ImpactPilot–HubSpot integration actually does under the hood — not just how to click "Connect."

The short version

ImpactPilot doesn't treat HubSpot as an import source you sync once and forget. It's built directly on top of the HubSpot company object: every Impact Driver status, every AI-detected risk, every point a CSM earns is modeled as a native HubSpot property, note, task, or deal — not a shadow copy living in a separate database that HubSpot users never see. If a Sales or RevOps team is looking at a company record in HubSpot, ImpactPilot's output is already there, in properties they can filter, report on, and build workflows against.

That design choice is what makes the rest of this document worth reading. Most "integrations" pull data one way. ImpactPilot's is a two-way, continuously reconciled system: HubSpot is the source of truth for CRM data, and ImpactPilot is the system of record for CS outcomes — written back into HubSpot's own schema in real time.

Authentication: standard OAuth, two scope tiers

ImpactPilot connects via HubSpot's standard OAuth 2.0 authorization-code flow, using HubSpot's official SDK for token exchange, refresh, and validation. There's nothing exotic here — no long-lived API keys, no service accounts to manage.

What's worth noting technically:

• Two scope tiers are requested, not one. A standard user-login flow requests a baseline scope set (reading and writing company properties, deals, owners, and sales-email data). Certain administrative actions — like creating new calculated properties in your HubSpot property schema — require a separate, elevated admin-scope grant, requested only when an admin performs an admin-gated action. ImpactPilot actively checks the current token's scopes against what an action requires before running it, rather than assuming a scope was granted once and stays valid forever.
• Tokens are validated against the org, not just decoded. Every privileged action re-verifies that the token's HubSpot Hub ID actually matches the organization the request claims to be acting for, closing off a class of cross-tenant token-confusion bugs common in multi-tenant OAuth integrations.
• Refresh is automatic. Access tokens are short-lived; ImpactPilot refreshes them transparently using the stored refresh token, so a connection doesn't silently degrade after HubSpot's token TTL expires — it just keeps working.

The scopes requested map directly to what's needed: read/write on company objects and schemas, read on deals and owners, read on contacts, and sales-email-read for engagement history — nothing broader than the feature set requires.

What flows in from HubSpot

On connection, and continuously afterward, ImpactPilot pulls:

• Company records — every standard and custom property, always merged with a fixed baseline (name, hubspot_owner_id, and your configured owner field) plus whatever properties your filters, Impact Drivers, and Account Plans currently reference. ImpactPilot doesn't guess which properties matter; it computes the exact set needed for the current configuration on each request.
• Engagements — emails, meetings, calls, and notes, fetched per company with configurable lookback windows and per-type toggles (you can turn off, say, call ingestion without touching email). This engagement stream is what feeds AI Insights and Signals — it's the raw material the AI evaluators read.
• Owners and users — resolved and cached so that "who owns this account" stays consistent across ImpactPilot's UI and HubSpot's.
• Property history — HubSpot retains roughly the last 30 revisions of any property. ImpactPilot's Trend Builder captures property snapshots on an ongoing basis specifically to outlive that limit, so a health-score trend from 14 months ago is still chartable even though HubSpot itself no longer has it.

All of this runs through a retrying HTTP layer: transient HubSpot API failures are retried automatically with exponential backoff (roughly 2s, 4s, 8s) before an error ever surfaces to a user, and company lookups support batched, parallelized requests rather than one-row-at-a-time polling — the difference that makes syncing a portfolio of thousands of accounts practical rather than theoretical.

What flows back into HubSpot — and how it's structured

This is the part that distinguishes ImpactPilot from a typical BI-style HubSpot add-on: the output isn't a dashboard. It's HubSpot data.

Impact Driver status → a real HubSpot company property

Every Impact Driver a CSM tracks can be mapped to its own HubSpot property. Change the status in ImpactPilot — manually, or via an automated Transition — and the mapped property updates in HubSpot in the same request. RevOps can build a HubSpot report or workflow off "Onboarding Complete = Closed Won" without ever opening ImpactPilot.

A dedicated, versioned property group for calculated metrics

ImpactPilot provisions its own HubSpot property group (distinct from the group used for Impact Driver status mappings) and creates properties inside it on demand — only for the metrics an org actually enables. As of writing, the built-in calculated-property catalogue includes:

Each property is created with the correct HubSpot field type up front (number, string, date, or percentage — with percentage properties getting HubSpot's native percentage display hint, not a raw 0–1 float a user has to mentally convert). If you later change a property's label, ImpactPilot detects the drift and pushes a label/type update to the existing HubSpot property rather than creating a duplicate.

Custom, expression-defined properties

Beyond the built-in catalogue, admins can define their own calculated properties using an expression language that can reference any HubSpot company property (including its historical values) and any ImpactPilot construct — points, account plan state, driver status. ImpactPilot validates the expression server-side before saving it, evaluates it per customer against freshly enriched HubSpot data, and pushes the result to a HubSpot property it provisions and names automatically. This is the mechanism that lets a CS org encode its own health-scoring logic once and have it live as a first-class, reportable HubSpot field — not a spreadsheet formula nobody else can see.

Activity notes and embedded plans

Configured status transitions can write a HubSpot note logging the change, and publishing an Account Plan can push a formatted note containing the plan's goals and milestones directly onto the company's HubSpot timeline — bounded to HubSpot's note-length limit, with truncation handled automatically rather than failing silently. Either way, the audit trail lives where your Sales and Success teams already look for it.

Signal Actions that write directly into your pipeline

Signals — ImpactPilot's real-time, per-event alerts — can trigger one-click Actions that create real HubSpot objects, not just in-app notifications:

• Create Task — an internal HubSpot task, AI-drafted, attached to the company record.
• Create Deal — a HubSpot deal, pre-filled with a title and description, placed into whichever pipeline and stage the CSM selects from the live list of pipelines available on your connected HubSpot account.
• AI Draft Email — composed from the Signal's evidence, reviewed and sent by the CSM through their own mail client (so it correctly carries their real signature).

None of these fire blind: manual Actions always produce a draft the CSM reviews before anything is created or sent.

The sync model: event-driven, not a nightly batch job

Data doesn't move on a fixed overnight schedule. ImpactPilot synchronizes:

• On login — a full refresh of the portfolio.
• On page load — an incremental check for anything changed since the last fetch.
• On any write — a targeted sync of just the affected record, dispatched as an asynchronous job rather than blocking the request that triggered it.

That async dispatch matters at scale: bulk recalculation (say, re-running every calculated property across your entire customer base after adding a new metric) is queued as a background job with its own status endpoint, so a 5,000-account portfolio recalculates without anyone staring at a spinner.

Precision, not a firehose: data filters and segments

Nothing about the sync model means "import everything." Admins define filter conditions directly against HubSpot company properties (lifecycle stage, revenue, any custom field) in AND/OR combination, and only companies matching those conditions enter ImpactPilot's dataset at all. The same property-condition engine underpins Segments, Signal scoping, and property-based Transition rules — one filtering model reused everywhere in the product, rather than three separate ad hoc implementations.

Why this matters

Put together, the integration gives you:

• A single schema. CS outcomes and CRM data live in the same HubSpot object, so there's no reconciliation step between "what Sales sees" and "what the CSM tracked."
• Extensibility without engineering. New calculated properties — built-in or custom-expression — appear in HubSpot automatically, typed correctly, grouped cleanly, with zero manual property administration.
• Durability beyond HubSpot's own limits. Trend Builder's independent history store means your longitudinal health-score or usage trends survive HubSpot's 30-revision cap.
• Real actions, not just visibility. Signals don't just tell a CSM something changed — their Actions create the task, the deal, or the note that HubSpot's own pipeline reporting will already pick up.

This is the difference between "HubSpot shows ImpactPilot data" and "ImpactPilot data is HubSpot data" — and it's why teams that live in HubSpot day-to-day don't have to change habits to benefit from it.