Hubspot troubleshooting

Debug HubSpot connection, webhook, ticket creation, and reply-sync issues — access-token failures, missing tickets, silent AI replies, broken handoffs.

Before debugging, have this ready:

• Access token status — is the integration showing as active in Settings → Integrations?
• Session ID — find it in the OpenCX inbox for the conversation in question.
• Webhook URL — copy it from the HubSpot integration settings in OpenCX.

Re-test the connection in Settings → Integrations → HubSpot as your first step. Many issues resolve with a fresh credential check.

Common scenarios

Connection test fails

Likely cause: expired or revoked access token, wrong token format, or missing scopes.

Fix:

1. In HubSpot, go to Settings → Development → Legacy Apps and check if the app is still active.
2. Confirm the token starts with pat- (region suffix varies — e.g. pat-na1-, pat-eu1-). If in doubt, regenerate it.
3. Verify all required scopes are enabled — see the scopes table.
4. Paste the new token in OpenCX and save.

Handoff runs but no ticket appears

Likely cause: the conversation didn’t originate from a channel HubSpot owns (most common), ticket creation is disabled, or the contact has no email for HubSpot to match.

Fix:

1. Check the channel. Tickets appear automatically only when the conversation starts from a channel HubSpot owns — a HubSpot chat widget, or an email routed through a HubSpot inbox. Messages sent to OpenCX’s [e-mail] address never reach HubSpot, so no ticket is created.
2. For non-HubSpot channels (OpenCX email, widget, WhatsApp, SMS, phone), use the create-hubspot-ticket-from-session workflow action on handoff. See Workflows for how to wire it.
3. Check with your OpenCX admin whether ticket creation is enabled for HubSpot.
4. Confirm the contact in the OpenCX session has an email address — HubSpot needs it to associate the ticket with a contact.
5. If all of the above are correct, check that the webhook is still registered in HubSpot (see below).

Rep replies don’t reach the customer

Likely cause: webhook not registered in HubSpot, wrong event subscriptions, uncommitted subscription changes, or stale webhook URL.

Fix:

1. In HubSpot, go to Settings → Integrations → Private Apps → Legacy Apps → your app → Webhooks.
2. Confirm subscriptions include Conversation → New message, Conversation → Conversation creation, and Ticket → Property change (with the relevant properties selected).
3. Confirm you clicked Commit changes after editing subscriptions — uncommitted changes don’t fire.
4. Re-copy the webhook URL from OpenCX and paste it in HubSpot if it looks stale.
5. Confirm the rep replied publicly, not as an internal comment — internal comments are not delivered to customers.

AI stopped replying mid-thread

Likely cause: the conversation owner is not the OpenCX AI user.

Fix:

1. In HubSpot, open the conversation and check the Assigned to field.
2. Reassign to the user whose ID you configured as the Default User ID in OpenCX.
3. If you want the AI to keep drafting while reps own the conversation, enable Assist Mode instead.

Webhook shows delivered in HubSpot but nothing happens

Likely cause: the webhook URL in HubSpot is stale or was copied from a different org.

Fix:

1. In OpenCX, re-copy the webhook URL at Settings → Integrations → HubSpot.
2. In HubSpot, open your Legacy App (Settings → Integrations → Private Apps → Legacy Apps) → Webhooks and replace the target URL.
3. Trigger a test conversation to confirm events are now processed.

Email reaches HubSpot, threads appear, but no OpenCX session is created

Likely cause: the Legacy App is missing the crm.objects.owners.read scope.

How to confirm:

1. In HubSpot, open your Legacy App → Monitoring → API Calls.
2. Look for GET /crm/owners/v3/A-<number> returning 403 with MISSING_SCOPES in the error body. This is the exact failure.

Fix:

1. Legacy App → Scopes tab → enable crm.objects.owners.read.
2. Click Save / commit scope changes.
3. In OpenCX Settings → Integrations → HubSpot, re-save to refresh the cached client.
4. Send a fresh test email and confirm the session now appears in the OpenCX inbox.

CRM context panel is empty

Likely cause: CRM integration not connected, or the contact’s email doesn’t match any HubSpot record.

Fix:

1. The CRM context panel is configured at Settings → CRMs — this is a separate connection from Settings → Integrations.
2. Confirm the contact’s email in OpenCX matches a contact in your HubSpot portal.
3. Test the CRM connection from Settings → CRMs.

OpenCX returns 200 OK to HubSpot webhooks immediately and processes them in the background. A successful webhook delivery in HubSpot’s logs does not guarantee processing succeeded on the OpenCX side.

Replies not syncing: full checklist

If handoff creates a ticket but replies do nothing:

1. Confirm the ticket has a handoff comment posted on the associated HubSpot conversation (AI summary, sentiment, language, OpenCX session link).
2. Check webhook event subscriptions in your HubSpot Legacy App settings — all three must be subscribed (Conversation → New message, Conversation → Conversation creation, Ticket → Property change).
3. Confirm you clicked Commit changes after adding or editing the subscriptions — uncommitted subscriptions don’t fire.
4. Confirm event throttling is set to 100 per second (or higher), not the default 10 — the default silently drops events during bursts.
5. Confirm the webhook URL in HubSpot matches the URL shown in OpenCX at Settings → Integrations → HubSpot.
6. Confirm the reply was sent as a public message, not an internal comment.
7. Check the customer’s channel is still reachable (email valid, phone active, widget session open).

Limits & timing

	Value
Webhook processing	Returns 200 OK immediately, async processing
Event delivery	At-most-once — failures are logged, not retried
Ticket close delay	~15 seconds before closing tickets on resolution
Transient failure retry	HubSpot API calls retry up to 3 times on error
Contact creation failure	Non-blocking — handoff proceeds even if the HubSpot contact can’t be created
Email channel delay	~5 seconds on email events to let concurrent workflows finish

OpenCX retries transient HubSpot API failures automatically but does not retry indefinitely past rate limits. If tickets are not appearing during a high-volume period, wait a few minutes and check again.

---

Related Documentation

Connect HubSpot

Re-check credentials, webhook, and email signatures.

Handoff & Sync

Re-check handoff behavior, ticket creation, and contact sync.

Webhook Reference

Event payloads, skip rules, and outbound HubSpot API calls.

Human Handoff

Global handoff settings and escalation rules.