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)
Known 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
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp