What HubSpot adds to Halo
HubSpot is Halo’s most capable integration — it does ingest, actions, and notifications:
Connect at Integrations > HubSpot.
Setup
Connecting
Click Connect HubSpot. You’ll be redirected to HubSpot’s OAuth consent screen. The required scopes:crm.objects.contacts.readandcrm.objects.contacts.writecrm.objects.companies.read(andcrm.objects.companies.writefor the two-way sync of companies)crm.objects.deals.readandcrm.objects.deals.writesales-email-readforms
Webhooks
Halo’s HubSpot app subscribes to webhooks for every portal that installs it, so there is nothing to configure. They carry:email.creation,note.creation,call.creation,meeting.creation— real-time engagement ingestcontact.*andcompany.*creation, property changes, deletions, merges and restores — the two-way sync
Two-way sync
Turn it on under Two-way sync on the integration page. A change on either side shows up on the other within about a minute (property changes HubSpot doesn’t send a webhook for arrive within 15 minutes).The mapping table
Each object, Contacts and Companies, has its own table. A row has four parts:
New setups start with name ⇄ full name, phone ⇄ phone and the contact’s company ⇄ the primary company, plus name, domain, industry and number of employees for companies. Add or remove rows as you need.
Fields that one side computes (Halo’s health score, MRR, renewal date; HubSpot’s deal counts, analytics source, email opt-out) can only flow out of that side. Mapping Halo’s health score to a HubSpot custom property is a good way to show account health to your sales team in HubSpot.
How a change syncs
Halo keeps, for every linked record and field, the value last synced on each side and when each side last changed it. HubSpot’s property history gives the HubSpot side’s time per property. When a record changes:- Only one side changed: its value goes to the other side (unless the row flows the other way).
- Both sides changed: the row’s rule decides. Latest change wins compares when each side’s change happened, field by field.
- A one-way row overwrites its target whenever the source changes. Edits on the target side stay until the source next changes.
(415) 555-0100 in Halo and +14155550100 in HubSpot, or a number stored as text on one side, is not treated as a change.
Matching and creating records
- Contacts are matched by email, companies by domain. Once matched, they stay linked by HubSpot id, so later email or domain changes don’t break the link.
- Create in Halo: HubSpot records with no match in Halo are added (contacts with source
hubspot, the way the ingest adds them). - Create in HubSpot: Halo records with no match in HubSpot are added. For contacts, choose leads only, product users only, or every contact with an email. Anonymous visitors are never sent. Clearing a contact’s company in Halo leaves the HubSpot association in place.
The first sync
Turning the sync on runs a full sync in the background. Halo reads every HubSpot company and contact and links them, then creates the unmatched Halo records in HubSpot. When both sides already hold different values for a field, the First sync setting decides which to keep. Empty fields are always filled from the side that has a value, and a first sync never empties a field. Adding rows to a running sync runs a full sync again, so existing records pick up the new fields. Run full sync does the same on demand.Deletes, merges, loops and missed events
- Deleting a record in HubSpot (including a GDPR deletion) stops the sync from writing to it; it is not deleted in Halo. Restoring it in HubSpot resumes the sync.
- Merging records in HubSpot keeps the surviving record linked; the merged-away records’ links stop. The Halo records stay as they are.
- Deleting a record in Halo stops it syncing; it is not deleted in HubSpot.
- Halo ignores the change events its own writes cause, so the two systems never overwrite each other in a loop.
- Every 15 minutes Halo searches HubSpot for records modified since the last pass, catching anything a webhook missed.
Required properties
If your HubSpot portal requires properties in its record creation settings, HubSpot refuses creates that omit them. Conditional required properties are enforced on every write whose condition applies, updates included. The sync then shows which properties the portal requires above the mapping table: map a Halo field to each of them (Halo → HubSpot), or relax the rule in HubSpot. Agent actions report the same when a write is refused.Permissions
Writing companies to HubSpot needs thecrm.objects.companies.write scope. If your connection predates it, the sync settings show the missing permission with a Reconnect button; reconnect once to grant it.
Ingest mode
When ingest is on, Halo syncs:
Engagement bodies are distillable — Halo can run an additional summarization pass to extract per-customer insights (“This customer prefers monthly invoices, account manager is Sarah, renewal in March”).
Sync behavior
- First connect: full backfill of all data
- Cron: hourly incremental sync (when
last_syncedis set and ingest is on) - Webhooks: real-time engagement events
- Manual sync: button on the integration detail page; supports
full_resync,catch_up,email_catch_up, andbackfill_transcriptsoptions
AI actions
Four actions enable on a per-agent basis at AI Agents > [Agent] > Actions:create_deal
Opens a new HubSpot deal for the conversation’s contact. Use when the user expresses buying intent or asks for a quote.
Configuration: default pipeline, default stage, default owner, default deal type. The action associates the deal with the matched contact when an email match is found.
update_contact
Patches a single property on the contact. Use sparingly — only properties you’ve allowlisted can be modified.
Configuration: allowed_properties list. Defaults: lifecyclestage, hs_lead_status, jobtitle, phone. The agent must confirm the change with the user before invoking.
log_activity
Creates a follow-up task on the contact in HubSpot. Use for “send pricing PDF tomorrow” or “call back about renewal.”
Configuration: task type (TODO / CALL / EMAIL), priority, default due date offset.
create_note
Attaches a free-form note to the contact in HubSpot. Use for handoff context, customer preferences, or AI summaries of conversations.
Configuration: optional body_prefix prepended to every note (e.g. “Halo AI summary:”).
Notifications mode
When HubSpot notifications mode is on AND Slack is connected with thenew_hubspot_engagement notification type enabled, Halo posts a Slack message every time a HubSpot engagement is processed.
The notification includes:
- The engagement type (email, note, call, meeting)
- The contact name and company
- A snippet of the body
- A link to the engagement in HubSpot
Stats and status
The integration page shows:- Total contacts, companies, deals, engagements synced
- Linked engagements (those associated with known Halo contacts)
- Last sync time
- Auth error or sync error banners when applicable
Disconnecting
Click Disconnect on the integration page to remove access. All ingested data stays in Halo but no further sync happens; the two-way sync turns off and forgets its links (records on both sides are kept). Reconnecting performs a fresh OAuth flow, triggers a new ingest sync, and starts the two-way sync from a fresh first sync.Where to go next
Agent Actions
Enable HubSpot actions per agent.
Slack
Set up Slack to receive HubSpot engagement notifications.
Learning Rules
Filter what gets learned from HubSpot engagement bodies.