Skip to main content
Inbound events HubSpot sends to OpenCX through the HubSpot app, plus the HubSpot API calls OpenCX makes back out. Shapes match the current implementation.
OAuth installs configure webhook delivery automatically. The legacy Private App path still uses an organization-specific webhook URL you copy from OpenCX.
HubSpot POSTs an array of events to OpenCX. OpenCX returns 200 OK immediately and processes in the background.
[
  {
    "eventId": 1234567890,
    "subscriptionId": 987654,
    "portalId": 12345678,
    "appId": 2345678,
    "occurredAt": 1713790000000,
    "subscriptionType": "conversation.newMessage",
    "attemptNumber": 0,
    "objectId": "9598272090",
    "changeSource": "CRM",

    "messageId": "abc-123",
    "messageType": "MESSAGE",
    "changeFlag": "NEW_MESSAGE",

    "propertyName": "hs_pipeline_stage",
    "propertyValue": "2"
  }
]
​
subscriptionType
string
required
Event type. OpenCX acts on supported HubSpot conversation, ticket, and note events. Everything else is ignored.
​
objectId
string
required
Thread ID (conversation events) or ticket ID (ticket events).
​
messageId
string
On conversation events, OpenCX re-fetches the message via GET /conversations/v3/conversations/threads/{threadId}/messages/{messageId} — the webhook envelope does not carry the message body.
​
messageType
'MESSAGE' | 'COMMENT'
COMMENT events are skipped (internal notes aren’t customer messages).
​
propertyName / propertyValue
string
Set on ticket.propertyChange. Empty values are ignored.
Re-fetches the message from HubSpot, then routes it through the AI if it passes filters.Skipped when: the sender is automated, a bot, or OpenCX’s own AI marker. HubSpot agent replies and internal notes are stored on the OpenCX session instead of being sent back to the AI.Email only: a 5-second delay lets other OpenCX workflows (drafting, signatures) finish first.Dedup key: message ID, scoped to the OpenCX organization.
Handles ownership changes. If the conversation is assigned away from the configured AI user, OpenCX marks the session as handed off unless Assist Mode is enabled.
Syncs the changed property onto the associated OpenCX session’s custom data.Skipped when: ticketing is disabled in settings, or propertyValue is null / empty string.
Mirrors HubSpot help-desk notes attached to a synced ticket into the OpenCX timeline as internal agent comments.

Connect HubSpot

OAuth setup, AI sender, workflow actions.

Handoff & Sync

Day-to-day handoff flow, rep replies, CRM context, contact sync.

Troubleshooting

Connection, webhook, ticket, and reply sync debugging.

HubSpot Overview

Capabilities and supported channels.