> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhook Reference
> HubSpot events OpenCX receives through the OAuth app and the HubSpot API calls OpenCX makes on handoff, reply, and close.
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.
```json Envelope theme={"dark"}
[
{
"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"
}
]
```
Event type. OpenCX acts on supported HubSpot conversation, ticket, and note events. Everything else is ignored.
Thread ID (conversation events) or ticket ID (ticket events).
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.
`COMMENT` events are skipped (internal notes aren't customer messages).
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.
On handoff and during the session lifecycle, OpenCX writes back to HubSpot through the OAuth connection.
Looks up the contact by email before creating a ticket. Creates one if missing.
```http theme={"dark"}
POST /crm/v3/objects/contacts/search
POST /crm/v3/objects/contacts
```
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.
```http theme={"dark"}
POST /crm/v3/objects/tickets
```
Posts an internal `COMMENT` on the HubSpot conversation thread with the AI summary, sentiment, language, and a link back to the OpenCX session.
```http theme={"dark"}
POST /conversations/v3/conversations/threads/{threadId}/messages
```
AI and agent-assist drafts are posted as public `MESSAGE` on the same conversation thread — email replies get the matching domain signature appended.
```http theme={"dark"}
POST /conversations/v3/conversations/threads/{threadId}/messages
```
When the OpenCX session resolves, the associated ticket is moved to the pipeline's closed stage. Delayed \~15s to stay within rate limits.
```http theme={"dark"}
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
OAuth setup, AI sender, workflow actions.
Day-to-day handoff flow, rep replies, CRM context, contact sync.
Connection, webhook, ticket, and reply sync debugging.
Capabilities and supported channels.