Connect HubSpot

OAuth-based HubSpot integration for CRM data flow — leads, deals, contacts sync from Wevion → HubSpot for richer attribution and ad-platform optimization. Setup at /connect/hubspot. Verified vs apps/backend/src/providers/hubspot/hubspot.provider.ts + plugin apps/backend/src/plugins/external/18.hubspot.ts.

Who is this for

Workspace owners and admins who:

• Use HubSpot as their primary CRM

• Want to enrich HubSpot contacts with ad-campaign attribution

• Want Wevion to push lead-gen form submissions into HubSpot in real time

• Need Wevion ad-event data in HubSpot contact timelines

What HubSpot integration does

Bidirectional sync (HubSpot → Wevion) limited to: deal stage updates (for closed-loop attribution).

Before you start

• A HubSpot account (Free, Starter, Professional, or Enterprise — features differ per HubSpot tier)

• A HubSpot user with admin role in the HubSpot account (needed for OAuth scopes)

• Wevion role: admin, owner, or super_admin

How to connect

Step 1: Open the HubSpot connector

In sidebar click Connect → HubSpot or visit /connect/hubspot. The page shows the Connect button + already-connected HubSpot accounts.

Step 2: Click Connect

A HubSpot OAuth popup opens. The popup shows the scopes Wevion requests:

• crm.objects.contacts.read + write — read/create Contacts

• crm.objects.companies.read + write — read/create Companies (B2B)

• crm.objects.deals.read + write — Deal stage updates

• timeline — write to contact event timeline

• e-commerce (if applicable) — for Shopify-HubSpot reconciliation

Step 3: Authorize

Sign in to HubSpot, pick which HubSpot account (if multiple), click Authorize. The popup closes and returns to Wevion.

Step 4: Wevion saves OAuth tokens

Backend stores access + refresh tokens encrypted at rest. HubSpot tokens auto-refresh; failure → yellow card → reconnect.

Step 5: Configure property mapping

/connect/hubspot → Property mapping lets you map:

• Wevion lead fields → HubSpot contact properties

• Default properties (email, first_name, last_name) auto-mapped

• Custom Wevion fields → custom HubSpot properties (you may need to create matching HubSpot properties first)

Property naming convention: Wevion uses wevion_* prefix for HubSpot custom properties to avoid conflict with HubSpot defaults or other integrations.

Important: post-PR #588 rebrand, all properties use wevion_* prefix (not legacy adrow_*). If you have old adrow_* properties from before the rebrand: keep them for backfill compatibility OR migrate via support.

Step 6: Trigger first sync

/connect/hubspot → Sync now button triggers a manual sync. Or wait for the next 15-min cycle.

OAuth token model

• Access token: short-lived (~6h)

• Refresh token: long-lived (renewed via auto-refresh; doesn't expire unless revoked)

• Encrypted at rest via Wevion's secret manager

• Token refresh handled by HubSpot provider

What you'll see when it works

• Connector card: green Connected badge

• HubSpot account name + Hub ID visible

• Property mapping count visible

• Recent sync timestamp shows < 15 min ago

• Toast: "HubSpot connected — syncing"

HubSpot architecture in Wevion

Verified file paths:

• apps/backend/src/plugins/external/18.hubspot.ts — plugin registration

• apps/backend/src/providers/hubspot/hubspot.provider.ts — API client

• apps/backend/src/services/hubspot.service.ts — business logic

• apps/backend/src/services/hubspot-outbox.service.ts — queued writes (avoid rate-limit issues)

• apps/backend/src/services/hubspot-reverse-etl.service.ts — bulk historical sync

• apps/backend/src/services/event-sinks/hubspot-event-sink.service.ts — streams Wevion events to HubSpot timeline

• apps/backend/src/sqs/workers/sync/hubspot-sync.worker.ts — async sync worker

• apps/backend/src/routes/api/admin-hubspot.route.ts — admin endpoints for sync management

• apps/backend/src/lib/enqueue-hubspot-sync.ts + apps/backend/src/lib/hubspot-event-id.ts — helpers

Multi-account HubSpot

Each HubSpot account = separate OAuth connection. If your team uses multiple HubSpot instances (e.g. agency managing client HubSpot accounts), connect each:

• Repeat steps 1-5 per account

• Each gets its own hubspot_connection row

• Property mapping per account (different HubSpot custom properties per account)

Security

• OAuth tokens encrypted at rest

• HubSpot scopes scoped to what's needed (CRM read/write only — no marketing email, no service hub)

• Audit log records every sync action (admin view)

• Revoke at HubSpot Settings → Integrations → Connected Apps → Wevion → Disconnect

Common issues

• OAuth popup blocked: enable popups for app.wevion.ai.

• "Insufficient permissions" error during OAuth: HubSpot user lacks admin role. Have admin perform the OAuth.

• Properties not appearing: custom HubSpot properties must exist in HubSpot before mapping. Create them first via HubSpot Settings → Properties.

• Sync stuck: HubSpot rate limit (default 100 req/10s per account). Wevion auto-throttles; check status after 1 hour.

• Legacy adrow_* properties showing: pre-rebrand properties retained for backward compat. Migrate to wevion_* via support if needed.

Related

• HubSpot leads sync — what flows — data flow details

• Integrations overview — context across all integrations

• Security best practices — OAuth + sensitive integration security