vendor/heap-track · vendor documented

Heap track calls need app_id and one identity

app_id is the environment ID. event is the custom name. Send identity for a known user or user_id for Heap's anonymous id, not both. Identify is vendor/heap-identify. Add user properties is vendor/heap-user-properties.

identity and user_id are exclusive

Heap documents one identifier. Sending both is rejected.

Rule: vendor.heap-track.body.identity_and_user_exclusive

What this pack matches

Hosts: heapanalytics.com, c.eu.heap-api.com
Paths: /api/track
Vendor docs: developers.heap.io/reference/track-1

Rules

Codes are stable. A finding in CI, MCP, or the playground lands on the same id.

Field	Required	What it checks	Rule ids	Source
`app_id`	required	It is the Heap environment ID. Heap documents it as required on every track call. Fix: Set `app_id` to the environment ID from Heap Projects.	`vendor.heap-track.body.app_id.missing` `vendor.heap-track.body.app_id.empty`	docs
`event`	required	It is the server-side event name. Heap documents it as required, limited to 1024 characters. Fix: Set `event` to the custom event name, such as `Purchase Completed`.	`vendor.heap-track.body.event.missing` `vendor.heap-track.body.event.empty`	docs
`identity`	optional	It identifies the user. Heap requires either `identity` or `user_id`, not both. Fix: Send the same identity you use in Heap Identify.	`vendor.heap-track.body.identity.empty`	docs
`user_id`	optional	It is Heap's anonymous user id. Heap requires either `identity` or `user_id`, not both.	`vendor.heap-track.body.user_id.empty`	docs
`timestamp`	optional	Heap documents `timestamp` as an ISO 8601 datetime. When omitted, Heap stamps the arrival time. Fix: Send an ISO 8601 timestamp, such as `2026-07-26T06:00:00Z`.	`vendor.heap-track.body.timestamp.empty` `vendor.heap-track.body.timestamp.invalid`	docs
`idempotency_key`	optional	Heap uses it to drop duplicate track calls.	`vendor.heap-track.body.idempotency_key.empty`	docs
`body.identity_or_user_required`	required	The track call has neither `identity` nor `user_id`. Heap documents one of them as required. Fix: Send `identity` for a known user, or `user_id` for an anonymous Heap id.	`vendor.heap-track.body.identity_or_user_required`	docs
`body.identity_and_user_exclusive`	required	The track call sends both `identity` and `user_id`. Heap documents those as mutually exclusive. Fix: Send one identifier, not both.	`vendor.heap-track.body.identity_and_user_exclusive`	docs

Validate a payload

pixellint validate json @payload.json --rulepack vendor/heap-track

Try this failing payload in the playground. Heap track missing identity and user_id.

{"app_id":"1234567890","event":"Purchase Completed"}

cargo install pixellint · npm install pixellint