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)

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

Create HubSpot Timeline Event Types and post custom timeline events to CRM contact records to track external product activity

developers.hubspot.com · 6 steps · unrated

Give your agent this knowledge — and 15,500+ more routes

One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus: claude mcp add --transport http waymark https://mcp.waymark.network/mcp

Track HubSpot custom behavioral events via the Events API to capture product analytics

Steps

Known gotchas

Related routes

Give your agent this knowledge — and 15,500+ more routes

Need this verified for your stack — or a route we don't have yet?