Connect HubSpot

Copy the OpenCX webhook URL, create a HubSpot Legacy App with scopes and webhook subscriptions, paste the access token, and configure email signatures.

One-time setup to connect HubSpot to OpenCX. After this, conversations hand off as tickets and messages sync both ways.

Setup takes about 15 minutes. You need admin access in both HubSpot and OpenCX.

Before you start

HubSpot account with Service Hub

The integration uses HubSpot’s conversations and ticketing APIs. Service Hub (Starter or above) is required.

HubSpot admin access

You need permission to create Legacy Apps and manage webhook subscriptions in your HubSpot portal.

Owner or admin in OpenCX

Only organization owners and admins can save integration credentials in the OpenCX dashboard.

Setup

You’ll jump between OpenCX and HubSpot twice: first to copy the webhook URL out of OpenCX, then to configure the full Legacy App in HubSpot (including webhooks), then back to OpenCX to paste the access token and user ID. Do it in this order — the webhook URL must be set in HubSpot before the app is created.

1. Copy your OpenCX webhook URL

   Open Settings → Integrations → HubSpot in your OpenCX dashboard.

   The integration modal shows a Webhook URL at the top. Copy it now — you’ll paste it into HubSpot’s Webhooks tab in the next step. You don’t need to fill in any fields in OpenCX yet; the webhook URL is available immediately and tied to your organization.

   The webhook URL is signed and specific to your organization. Treat it like a password.

2. Create a HubSpot Legacy App (private)

   In HubSpot, go to Settings → Integrations → Private Apps → Legacy Apps → Create Legacy App and choose Private.

   HubSpot opens a wizard with three tabs: App info, Scopes, and Webhooks. Fill all three tabs below before clicking Create app at the top — the webhook URL must be saved with the app, not added later.

   HubSpot now groups private apps under Legacy Apps inside the Integrations section. The flow and capabilities are unchanged and fully supported — the “legacy” label is HubSpot’s naming, not a deprecation signal for this integration.

3. Tab 1 — App info

   Enter a recognizable name (e.g. OpenCX) and a short description. The logo is optional.

4. Tab 2 — Scopes

   Enable every scope in this table. Missing scopes cause silent 403s at runtime.

   Scope	Purpose
   crm.objects.contacts.read	Look up contacts by email
   crm.objects.contacts.write	Create new contacts on handoff
   crm.objects.companies.read	Fetch company data for CRM context
   crm.objects.deals.read	Fetch deal data for CRM context
   crm.objects.owners.read	Resolve the AI user’s owner record for conversation ownership checks. Missing this scope silently drops inbound webhooks with a 403 on /crm/owners/v3/<id>.
   tickets	Create, update, and close handoff tickets
   conversations.read	Read incoming messages
   conversations.write	Post AI and rep replies

5. Tab 3 — Webhooks

   This tab has four things to set. Do them in order.

   1. Target URL. Paste the OpenCX webhook URL you copied in Step 1.

   2. Event throttling. Change the default from 10 events per second to 100 events per second. The default is too low for production volume and will drop events during busy periods.

   3. Create subscriptions. Click Create subscription. Each subscription uses two dropdowns: an Object type and an Event. Create these three subscriptions:

   Object type	Event	Notes
   Conversation	New message	Main inbound trigger — fires on every new customer message.
   Conversation	Conversation creation	Fires when a new thread is opened.
   Ticket	Property change	See below — this one also asks which properties to watch.

   For the Ticket → Property change subscription, HubSpot asks you to pick which ticket properties to watch. Select at least:

   • subject
   • content
   • hs_pipeline_stage
   • hs_ticket_priority
   • Any custom ticket properties you want mirrored back into the OpenCX session.

   These property values flow back into the OpenCX session’s editable custom data whenever an agent edits the ticket in HubSpot.

   4. Commit changes. Click Commit changes at the top of the Webhooks tab. Subscriptions do not activate until they’re committed — this is easy to miss.

   HubSpot’s Conversation object type does not expose an event called “Message created” — only New message and Conversation creation. If earlier docs mentioned conversation.messageCreated, it was wrong. Stick to the two events above.

6. Create the app and copy your access token

   Click Create app at the top of the wizard. HubSpot generates two values on the app page:

   • Access Token — starts with pat-<region>-... (e.g. pat-na1- for North America, pat-eu1- for EU). This is the only value OpenCX needs.
   • Client Secret — shown next to the access token. Not used by this integration. You can ignore it.

   Copy the access token immediately — HubSpot shows it only once. If you miss it, you can rotate and re-copy it from the app’s auth page.

   The Client Secret is part of HubSpot’s public-app OAuth flow. This integration uses Private App Bearer auth with the access token only, so the Client Secret is never sent anywhere.

7. Find your numeric user ID

   The Default User ID is the HubSpot user that AI replies are sent as. You’ll find it in the user’s settings URL.

   1. In HubSpot: Settings → Users & Teams.

   2. Click the user who should own AI replies.

   3. Look at the browser URL — it looks like:

      https://app.hubspot.com/settings/<PORTAL_ID>/users/<USER_ID>

      The <USER_ID> at the end is a plain number (e.g. 71822709).

   4. Copy only the number — do not include any prefix.

   Enter the numeric ID only (e.g. 71822709). Do not include an A- prefix even if the OpenCX input placeholder suggests it — OpenCX prepends A- internally when calling HubSpot. Entering A-71822709 causes AI replies to fail silently.

8. Paste credentials into OpenCX and save

   Return to the HubSpot integration modal in OpenCX (Settings → Integrations → HubSpot).

   Field	Value
   Access Token	The pat-... token from Step 6.
   Default User ID	The numeric user ID from Step 7 (no prefix).

   Click Save. OpenCX verifies the token and auto-detects your HubSpot portal.

   Before testing, enable Autopilot for the channel you’ll use (Email, Web, etc.) in Settings → Autopilot. Autopilot is set per-channel — OpenCX silently skips incoming HubSpot messages for any channel where it’s off.

   See Webhook Reference for the exact event payload shape, per-event skip rules, and the HubSpot API calls OpenCX makes back.

9. Verify end to end

   For a HubSpot ticket to appear from a test message, the conversation must originate from a channel HubSpot owns — either a HubSpot chat widget or an email address routed through a HubSpot inbox. HubSpot creates the ticket on its side, OpenCX just links to it.

   Messages sent to an OpenCX [e-mail] email address will not create HubSpot tickets. That channel is OpenCX-native — HubSpot never sees the message, so there’s no ticket to create. Use an email address connected to your HubSpot inbox, or embed the HubSpot chat widget, to test end-to-end.

   Test via a HubSpot-connected email inbox:

   1. Send a test email to an address that routes into your HubSpot inbox (the same address you’d give a real customer).
   2. Confirm the thread appears in HubSpot’s inbox and HubSpot auto-creates an associated ticket.
   3. Confirm a matching session appears in the OpenCX inbox.
   4. Let the AI reply — confirm the reply posts back on the same HubSpot thread and reaches the customer’s mailbox.
   5. Trigger a handoff — confirm an internal handoff comment appears on the HubSpot conversation with the AI summary, sentiment, language, and a link back to the OpenCX session.

   Test via the HubSpot chat widget: embed the widget on a test page, send a message, then repeat the confirmations above.

   If you need HubSpot tickets from non-HubSpot channels (OpenCX’s own email, widget, WhatsApp, SMS, or phone), use the create-hubspot-ticket-from-session workflow action instead — it creates the ticket directly via the HubSpot API on handoff.

   If any step fails, check Troubleshooting for common causes.

Email signatures

Append branded email signatures to outgoing replies sent through HubSpot. Signatures are matched to the sender’s email domain, so different domains can have different signatures.

1. Open HubSpot settings

   Go to Settings → Integrations → HubSpot in your OpenCX dashboard.

2. Add a signature

   Scroll to Email Signatures and click Add. Enter the domain pattern and paste your signature HTML.

3. Add more domains (optional)

   Repeat for each domain that needs a different signature.

Domain matching

Pattern	Matches
open.cx	Emails from open.cx only (exact match)
*.nl	All emails ending with .nl (wildcard)
*.co.uk	All emails ending with .co.uk (wildcard)

Exact domain matches always take priority over wildcard patterns. If you have both open.cx and *.cx, emails from open.cx use the exact-match signature.

Disconnecting

To disconnect, click Disconnect in Settings → Integrations → HubSpot. Then remove the webhook subscriptions from your HubSpot Legacy App (Settings → Integrations → Private Apps → Legacy Apps → your app → Webhooks) to stop event delivery.

---

Related Documentation

Handoff & Sync

Ticket creation, contact sync, CRM context.

Troubleshooting

Connection failures, missing tickets, reply sync issues.

HubSpot Overview

Capabilities, supported channels, observability.

Human Handoff

Global handoff settings and escalation rules.