Skip to main content
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

: expired or revoked access token, wrong token format, or missing scopes. Fix:
  1. In HubSpot, go to Settings → Integrations → Private Apps and check if the app is still active.
  2. Confirm the token starts with pat-na1-. 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

: ticket creation is disabled, or the contact has no email address for HubSpot to match. Fix:
  1. Check with your OpenCX admin whether ticket creation is enabled for HubSpot.
  2. Confirm the contact in the OpenCX session has an email address — HubSpot needs it to associate the ticket with a contact.
  3. If both are correct, check that the webhook is still registered in HubSpot (see below).

​
Rep replies don’t reach the customer

: webhook not registered in HubSpot, wrong event subscriptions, or stale webhook URL. Fix:
  1. In HubSpot, go to Settings → Integrations → Private Apps → your app → Webhooks.
  2. Confirm subscriptions include conversation.newMessage, conversation.messageCreated, and ticket.propertyChange.
  3. Re-copy the webhook URL from OpenCX and paste it in HubSpot if it looks stale.
  4. Confirm the rep replied publicly, not as an internal note — internal notes are not delivered to customers.

​
CRM context panel is empty

: 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 the opencx_handedoff tag in HubSpot.
  2. Check webhook event subscriptions in your HubSpot Private App settings — all three events must be subscribed.
  3. Confirm the webhook URL in HubSpot matches the URL shown in OpenCX at Settings → Integrations → HubSpot.
  4. Confirm the reply was sent as a public message, not an internal note.
  5. Check the customer’s channel is still reachable (email valid, phone active, widget session open).

​
Limits & timing

Value
Webhook processingReturns 200 OK immediately, async processing
Ticket update rate limit15 seconds between updates
Transient failure retryRetries automatically on temporary HubSpot API errors
Contact creation failureNon-blocking — handoff proceeds even if the HubSpot contact can’t be created
Email channel delayShort delay on email messages to allow workflows to complete
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.

Connect HubSpot

Re-check credentials, webhook, and email signatures.

Handoff & Sync

Re-check operational behavior and assist mode.

Human Handoff

Global handoff settings and escalation rules.

Autopilot

Control which topics the AI resolves vs escalates.