HubSpot setup

This guide connects HubSpot as Escalate's CRM source. Escalate uses OAuth + the deal-stage webhook (no HubSpot Marketplace review for V1 install). Plan ~10 minutes including the first retrofit run.

What you'll need

• Admin role: HubSpot Super Admin OR a custom role with App Marketplace → Install apps + read access to Deals. Escalate's app is self-installable for the V1 design-partner phase (unlisted; no marketplace approval).
• Portal ID: found at Settings → Account Setup → Account Defaults. A 6–10 digit number (e.g., 12345678). Escalate resolves it automatically during the OAuth handshake — you only need to know it for support emails.
• OAuth scopes Escalate requests (self-installable):
  • crm.objects.deals.read — read deal records (no writes).
  • crm.schemas.deals.read — read your deal-stage configuration (Escalate needs this to know which stages match your trigger).
  • oauth — required by every HubSpot OAuth flow; covers token refresh.

Escalate never writes to your HubSpot portal. Reads are scoped to deals at or past your configured trigger stage. No deletes, no updates, no field writes. The DPA is the binding contract.

Step-by-step

1. In Slack, run /escalate config crm. Pick HubSpot from the vendor picker; Escalate posts a one-time install URL good for 5 minutes. Click it.

2. HubSpot opens the standard OAuth consent screen showing all three scopes. Review and click Connect app. (If you have multiple portals on the same account, HubSpot prompts you to pick which portal to install into — confirm it's the production portal you want Escalate watching.)

3. HubSpot redirects back to Escalate. You'll see a "HubSpot connected" confirmation page listing the workspace ID and the trust panel. Close that tab.

4. Back in Slack, run /escalate config trigger. Pick the deal stage that should trigger channel auto-creation. HubSpot stage IDs come from the deal-stage picker in your portal — Escalate enumerates them for you in the modal. Set the minimum deal amount if you want to filter for higher-ACV opportunities.

5. Run the first retrofit. Unlike Salesforce, HubSpot's webhook ONLY fires on NEW stage transitions — past deals that already sit at your trigger stage are invisible to the webhook. Run /escalate retrofit and pick last 30 days to pull deals that already qualified. Without this, you'll see zero channels on Day 0.

Troubleshooting

OAuth-callback errors map to the following fixes. The exact error messages match what HubSpot + Escalate's OAuth helper return.

"Connection to HubSpot failed during token exchange."

Cause: HubSpot rejected the OAuth code. Usually a stale browser tab or a redirect URL mismatch (rare in production). Fix: Run /escalate config crm again to get a fresh install link.

"Could not identify your HubSpot portal."

Cause: Escalate's portal-id introspection call failed. HubSpot's token-info endpoint was temporarily unavailable. Fix: Wait 60 seconds and try again. If it persists past 2 attempts, ping the founder with the workspace name.

"Saving the connection failed (database error)."

Cause: Escalate's database hit a transient error during persist. Fix: Retry. Past 2 attempts → ping the founder.

"This connection request has expired or already been used."

Cause: OAuth state tokens are single-use and expire after 15 minutes. Fix: Run /escalate config crm again.

Channels stop auto-creating after a few weeks

Cause: HubSpot refresh tokens occasionally rotate or get revoked when an admin changes app-install settings. Escalate has an auto- recovery path (it detects the failure on the next poll and DMs you to re-run /escalate config crm). Fix: Re-run /escalate config crm; the auto-recovery path will silently re-issue a fresh refresh token, and a same-PR retrofit will pull any gaps from the outage window.

Webhook fires but no channel appears

Cause checklist:

• Does the deal exceed your minimum-amount filter? Check /escalate config trigger.
• Was the deal created at the trigger stage, or did it transition into it? Webhook-based path only fires on transitions; deals created directly at the trigger stage won't fire the webhook (use retrofit for those).
• Has Slack rate-limited Escalate's channel-create call? Check Slack's workspace audit log; if you hit a rate limit, channel creation retries with backoff.

How to find your HubSpot portal ID

The portal ID is only relevant if you're emailing support; Escalate's slash commands never require you to type it.

• From HubSpot: Settings → Account Setup → Account Defaults → Portal ID at the top.
• From a HubSpot URL: any URL containing app.hubspot.com/... — the portal ID is the digit segment immediately after /contacts/ or /sales/ (e.g., app.hubspot.com/contacts/12345678).
• From the Escalate console: the portal ID appears on the Coverage Report header next to your workspace name.