Skip to main content
Inbound events HubSpot sends to your OpenCX webhook URL, plus the HubSpot API calls OpenCX makes back out. Shapes match the current implementation — no abstractions.
HubSpot POSTs an array of events to your OpenCX webhook URL. OpenCX returns 200 OK immediately and processes in the background — at-most-once, no redelivery on failure.
[
  {
    "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 only acts on three — 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: messageType === 'COMMENT', sender is BOT or AGENT, messageDirection === 'OUTGOING', the text contains OpenCX’s own AI markers (🔄 AI decided to handoff or <!-- OpenCX-AI-Response -->), or the conversation owner is not the configured AI user.Email only: a 5-second delay lets other OpenCX workflows (drafting, signatures) finish first.Dedup key: ${objectId}-${messageId ?? eventId} within a single delivery batch.
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.
If the HubSpot conversation is owned by a user other than your configured AI user, OpenCX stops replying. Reassign to the AI user to resume — or enable Assist Mode, which ignores owner checks and posts drafts as internal comments.

Connect HubSpot

Legacy App, scopes, access token, and webhook registration.

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.