Skip to content
HeyX API

Create Customer Event

Required scope: customer_event:create

Use this endpoint when an external system needs to record a timeline event without creating a HeyX-native entity first.

Set externalId to a stable source-system identifier. It is an idempotency key scoped to the customer: retries return the original eventId and occurredAt and do not create another event, even after the canonical event reaches its retention limit.

Generated Reference
POST /public-api/publicapi.v1.CustomerEvent/CreateCustomerEvent

Adds an externally-observed event to a customer timeline.

Request CreateCustomerEventRequest
Response CreateCustomerEventResponse

CreateCustomerEventRequest

Field Type Description
customer_id string
event_type string
summary string
payload_json string
occurred_at optional int64
external_id optional string Idempotency key scoped to this customer. Retries return the original event.

CreateCustomerEventResponse

Field Type
event_id string
occurred_at int64

Request

Section titled “Request”
{
  "customerId": "be85f4d1-b680-4964-bf62-9828fdf4ce04",
  "eventType": "external.status_changed",
  "summary": "External status changed",
  "payloadJson": "{\"status\":\"received\"}",
  "externalId": "erp-event-123"
}

Response

Section titled “Response”
{
  "eventId": "14d7d8d7-49de-42db-bb49-c835b274d63f",
  "occurredAt": 1760000000
}
HeyX API