HubSpot

Connect your Gravity Rail workspace to HubSpot CRM. The integration links workspace members to HubSpot contacts and gives your AI assistants the ability to query, create, and update HubSpot records during conversations.

The integration uses OAuth 2.0 with encrypted token storage. One HubSpot account connects to one workspace.

Prerequisites

Before connecting, you need a HubSpot app (a private app or a developer app) configured for OAuth. If you don't have admin access to HubSpot, you'll need someone on your HubSpot team to set this up.

Create a HubSpot app

You need a Client ID and Client Secret from a HubSpot app.

1. In HubSpot, go to Settings → Integrations → Private Apps (or create a developer app at developers.hubspot.com).
2. Give the app a name (e.g. Gravity Rail).
3. Under Auth, set the Redirect URL to the OAuth callback URL shown in step 1 of the guided setup on the HubSpot connection page in Gravity Rail (see Connection setup below).
4. Add these CRM scopes:
   • crm.objects.contacts.read / crm.objects.contacts.write
   • crm.objects.companies.read / crm.objects.companies.write
   • crm.objects.deals.read / crm.objects.deals.write
5. Save. HubSpot shows a Client ID and Client Secret — you'll need both.

Connection setup

Setup is guided. After you install HubSpot, the connection page walks you through the remaining steps and shows where you are. You don't need any credentials to begin — the OAuth callback URL you must register in HubSpot is shown in step 1 of the guide, before you enter anything. (There's no chicken-and-egg: the callback URL depends only on your workspace, not on the HubSpot app you haven't created yet.)

Step 1: Install HubSpot

In Apps & Connections (or Channels in the sidebar), find HubSpot and click Install. This creates the connection and opens its setup page with a Setup in progress badge and a three-step guide. If HubSpot isn't listed, the crm_hubspot feature flag may not be enabled on your workspace -- contact your Gravity Rail administrator.

Step 2: Register the callback URL in HubSpot

The guide's first step shows your OAuth Callback URL:

https://api.gravityrail.com/api/v2/w/{your-workspace-uuid}/app-connections/hubspot/oauth/callback

Copy it (there's a copy button) and set it as the Redirect URL on your HubSpot app, along with the CRM scopes listed in the same step (see Create a HubSpot app). The URL must match exactly, including the protocol and path. HubSpot then gives you a Client ID and Client Secret.

Step 3: Enter your credentials

Click Enter credentials in the guide's second step, enter the Client ID and Client Secret from your HubSpot app, and click Create to save. The second step is now checked off.

Step 4: Authorize with HubSpot

Click Connect with HubSpot in the guide's third step. A new browser window opens to the HubSpot authorization page.

1. Choose the HubSpot account to connect
2. Review the permissions and click Connect app
3. The window redirects back to Gravity Rail and closes

The connection status changes to Connected. Your HubSpot Portal ID appears on the Overview tab, where the callback URL and scopes remain available under Setup & Auth for future reference.

Set up from the command line (optional)

The same steps are available through the Gravity Rail CLI -- handy for scripted setup or when a workspace agent performs the configuration. Run gr hubspot install --help for the full sequence.

# 1. Create the connection. The response includes the OAuth "callbackUrl".
gr hubspot install -w <workspace-uuid> --allow-write

# 2. Register that callbackUrl + scopes on your HubSpot app, then save credentials.
gr hubspot configure -w <workspace-uuid> --allow-write \
  -d '{"clientId":"...","clientSecret":"..."}'

# 3. Authorize. Open the returned "authorizeUrl" in a browser to grant access.
gr hubspot authorize -w <workspace-uuid> --allow-write

# Check progress at any time (shows configured / connected + the callback URL).
gr hubspot status -w <workspace-uuid>

Connection states

State	Badge	Meaning
Setup in progress	Secondary	Installed, but credentials haven't been entered yet -- the guided setup is showing
Awaiting OAuth	Secondary	Credentials are saved but OAuth authorization hasn't been completed yet
Connected	Green	OAuth is complete and the API connection is active
Error	Red	Something went wrong (see Troubleshooting)
Not Connected	Secondary	No connection has been configured

Troubleshooting

redirect_uri_mismatch error during OAuth

The Redirect URL registered in your HubSpot app doesn't match the one Gravity Rail is using. Copy the OAuth Callback URL from the guided setup (step 1) or, once connected, from the Setup & Auth card on the Overview tab, and update your HubSpot app to use that exact URL.

Connection stuck on "Setup in progress" or "Awaiting OAuth"

"Setup in progress" means credentials haven't been saved -- use Enter credentials in the guide. "Awaiting OAuth" means credentials are saved but the OAuth flow didn't complete -- click Connect with HubSpot to start it (the OAuth state is valid for 10 minutes).

Connection shows "Error" state

The access token may have been revoked, or a required scope is missing. Click Disconnect, then Connect with HubSpot to reauthorize. If a specific API call fails, confirm the app has all six CRM scopes.

Related

• Channels -- Overview of all communication channels and integrations
• HubSpot Sync -- Field mapping, sync rules, and data sync configuration