Webhook Reference

Payloads HubSpot sends to OpenCX and HubSpot API calls OpenCX makes on handoff, reply, and close.

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.

Inbound (HubSpot → OpenCX)

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.

Envelope

[
  {
    "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.

conversation.newMessage / conversation.messageCreated

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.

ticket.propertyChange

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.

Owner gating

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.

Outbound (OpenCX → HubSpot)

On handoff and during the session lifecycle, OpenCX writes back to HubSpot through the Legacy App access token.

Find or create contact

Looks up the contact by email before creating a ticket. Creates one if missing.

POST /crm/v3/objects/contacts/search
POST /crm/v3/objects/contacts

Create handoff ticket

Opens a ticket associated with the contact. Subject, content (conversation summary), pipeline/stage, priority, owner, and any session custom_data / editable_custom_data are written as ticket properties.

POST /crm/v3/objects/tickets

Post handoff comment

Posts an internal COMMENT on the HubSpot conversation thread with the AI summary, sentiment, language, and a link back to the OpenCX session.

POST /conversations/v3/conversations/threads/{threadId}/messages

Reply to customer

AI and agent-assist drafts are posted as public MESSAGE on the same conversation thread — email replies get the matching domain signature appended.

POST /conversations/v3/conversations/threads/{threadId}/messages

Close ticket on resolution

When the OpenCX session resolves, the associated ticket is moved to the pipeline’s closed stage. Delayed ~15s to stay within rate limits.

PATCH /crm/v3/objects/tickets/{ticketId}

Transient HubSpot API errors retry up to 3 times. Contact creation failures are non-blocking — handoff still proceeds. OpenCX only writes properties that exist in your HubSpot schema; unknown fields are skipped silently.

---

Related Documentation

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.