Custom events are how you bring product behavior, in-app actions, and offline interactions into HubSpot’s contact timeline and reporting. They sound straightforward and become a mess fast if you skip the design step. Below is the implementation pattern that survives.
What you get with custom events
Marketing Hub Enterprise unlocks custom event creation with up to 30 properties per event. Events appear in the contact timeline, can trigger workflows, populate lists, and feed into reports. Below Enterprise you can fire behavioral events via the Tracking Code API but reporting is limited.
Naming convention up front
Use verb_noun lowercase with underscores: viewed_pricing, started_trial, completed_onboarding. Reserve a prefix for source: web_, app_, crm_. Without a convention, you end up with Pricing Page View, pricingViewed, and viewed pricing as three different events.
Property schema discipline
For every event, define required properties (event name, occurred at, contact identifier) and optional context (URL, plan tier, value, source). Document the schema in a sheet outside HubSpot. The HubSpot UI does not enforce schema across events; your governance does.
Sending events: client vs server
Client-side via the Tracking Code API (_hsq.push(['trackCustomBehavioralEvent', {...}])) is fine for marketing site events. Server-side via the Events API is the right call for transactional or product events that need to fire even when JS is blocked. Mixing both is normal; document which lives where.
Identifying the contact
Events without a known contact get associated when the contact later identifies themselves (form fill, login). Always pass an email or utk (HubSpot user token) when known. Anonymous events sit in a separate bucket until association resolves.
Volume planning
Custom events count toward Marketing Hub limits. A click event firing on every button on every page burns through quota fast. Whitelist the events that drive workflows or reports; do not log everything because you can.
Workflow patterns from custom events
Trigger a workflow on event occurred at least N times in past X days to enroll contacts whose behavior crosses a meaningful threshold. Avoid triggering on single occurrence of low-signal events; the workflow becomes a firehose and re-enrollment compounds the noise.
Event analytics
Use Reports > Custom report > Single object > Events to slice by event name, contact properties, and time. The default event report is shallow; build custom reports for the events that actually drive decisions.
What to do this week
Inventory the custom events firing today, document the schema and naming convention, and turn off any events that have no consumer (workflow, report, list). Add the schema doc to your tracking governance.
