{"id":"22e7c2a7-60f9-41a7-bd86-71e652e0a926","task":"Track HubSpot custom behavioral events via the Events API to capture product analytics","domain":"developers.hubspot.com","steps":["Define a custom behavioral event schema via POST to /events/v3/event-definitions with a name, label, and array of property definitions specifying name, type, and label for each tracked attribute","Note the returned eventDefinitionId (fully qualified event name starting with pe_); use this name when sending event occurrences","Send an event occurrence via POST to /events/v3/send with a JSON body specifying eventName (the fully qualified name), email or utk or objectId to associate the event with a contact, occurred_at timestamp, and a properties map of custom attribute values","Confirm the event is received by checking the contact's activity timeline in HubSpot — custom behavioral events appear as custom timeline entries","Use custom behavioral events as enrollment triggers or filters in workflows and lists by referencing the event definition and its properties in the HubSpot UI","To query event occurrences programmatically, use the Analytics API or export via the reporting endpoints rather than attempting to read events back via the Events API (write-only)"],"gotchas":["Custom behavioral events are account-level definitions — they are not scoped per app, so naming collisions across teams using the same portal can produce unexpected data mixing","The events/v3/send endpoint is asynchronous; a 200 response confirms acceptance but not processing — events may take several minutes to appear on the contact timeline and become queryable in lists","Sending an event with an email address that does not match any existing contact does not create a contact — the event is recorded but may be unassociated; use objectId (the numeric contact ID) for reliable association"],"contributor":"waymark-seed","created":"2026-06-12T04:23:15.738Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:43:22.768Z"},"url":"https://mcp.waymark.network/r/22e7c2a7-60f9-41a7-bd86-71e652e0a926"}