Skip to Content
IntegrationsHubSpotGetting started

HubSpot Integration — Onboarding

Prerequisites

  • A HubSpot account with CRM access and at least one active deal pipeline.
  • HubSpot user account with Super Admin or App Marketplace Access permission (required to install OAuth apps).
  • FlowState tenant with owner or admin role (both carry tenant:integrations:hubspot:connect).

Connect with OAuth

OAuth is the only supported connection method. It grants scoped, revocable access and supports real-time webhooks, which means APN sync happens within seconds of a deal change.

Steps

  1. Go to Settings → Integrations → HubSpot in FlowState.
  2. Click Connect HubSpot.
    • FlowState opens HubSpot’s OAuth authorization page in a new window. The URL is pre-filled with FlowState’s app client ID and the required scopes.
  3. In HubSpot, you see a consent screen listing the scopes FlowState is requesting and which portal they apply to.
    • If you manage multiple HubSpot portals, confirm that the correct portal is shown in the top-right corner. Switch portals if needed before authorizing.
  4. Click Connect app.
    • HubSpot redirects back to FlowState’s callback URL.
  5. FlowState exchanges the authorization code for an access token and refresh token, stores the refresh token securely, and immediately triggers the first pipeline fetch.
  6. The UI shows a green Connected badge alongside your HubSpot portal ID and the scopes that were granted.

Connecting does not provision the custom properties or check the webhook subscription — the OAuth callback only stores tokens and enqueues that first pipeline fetch. Provisioning is a separate, explicit step:

  1. Go to Settings → Integrations → HubSpot and click Provision properties (or call the provision_hubspot_properties MCP tool). This creates the flowstate_apn property group and all 10 APN custom properties in your HubSpot portal. This step is idempotent — re-running it never overwrites existing property values, and you can re-run it at any time, not just once at connect.

The webhook subscription itself is not per-tenant — FlowState’s HubSpot app registers one shared subscription that covers every connected portal, configured in the app’s manifest rather than set up per connection. There is no separate step to verify it during onboarding.

What you see if something goes wrong

  • “Authorization cancelled” — you clicked Cancel in HubSpot. Click Connect HubSpot again.
  • “State mismatch” — the CSRF token expired (more than 15 minutes passed between clicking Connect and authorizing). Start over.
  • “Insufficient scopes” — your HubSpot user account does not have permission to authorize one of the required scopes. Ask your HubSpot Super Admin to either grant you App Marketplace Access or connect on your behalf.
  • “Property provisioning failed” — at least one of the 10 custom properties could not be created. The most common cause is a pre-existing property with a conflicting type. See Troubleshooting for resolution steps.
OverviewPermissions & scopes