Skip to content
Analytics Tools

Create manually tracked behavioral events

Last updated: May 24, 2021

Applies to:

Marketing Hub  Enterprise

Manually tracked custom behavioral events enable to you define and track events that are unique to your business. Custom behavioral events can be tied to contact properties, which you can then use across HubSpot's tools. Manually tracked events use the analytics API, and require a developer to set up.

Learn how to use the custom behavioral event tool to create clicked element events and visited URL events.

Please note: the custom behavioral events tool replaces the previous behavioral events legacy tool. Any events created in the legacy tool will continue to work, and you can still manage and analyze those events in the legacy tool

The event creation process involves two parts:

  • Defining the event in HubSpot, including which contact properties you want to associate with the event.
  • Define the API call that will trigger the event. 

Create the event in HubSpot

To set up a custom behavioral event, you'll first create the event, then associate properties with the event:

  • In your HubSpot account, navigate to Reports > Analytics Tools.
  • Click Custom Behavioral Events.
  • In the upper right, click Create event.
  • In the right panel, enter a name for your event, then select Manually tracked event.
     create-manually-tracked-event
  • The event will then be created, and you'll be able to copy the internal name, which will be used when making the API request. To copy the internal name, click Copy.

Next, set up the properties that will be used in your API call.

Add and manage event properties

Creating properties for an event enables the event API call to send and store data in contact properties. When you create an event, a set of default event properties will be available for you to use, and you can also create your own custom properties. Event properties are stored separately from other CRM properties, and are unique to the event (i.e. you can't edit these properties from your account settings).

To view and create properties for an event:

  • In your HubSpot account, navigate to Reports > Analytics Tools.
  • Click Custom Behavioral Events.
  • Click the name of the event you want to view or update. You'll then be taken to the event details page.
  • In the Properties table, view the default properties that were created for the event. 
  • To edit a property:
    • Click the property name.
    • In the right panel, you can enter a new name or description. Changing the property name will not change the internal name, so you won't need to update your API call if you change the name of a property.
    • To change the field type and further configure the property, click the Field type tab, then use the dropdown menus to select a new field type and configure your property details. 
    • Click Save.
  • To create a new property:
    • In the upper right, click Create property.
    • In the right panel, configure the property:
      • Select a grouping for the property by clicking the Group dropdown menu, then selecting a group.
      • To set the name of the property, enter a name into the Label field. The name you enter will automatically create the internal name for the property. To edit the internal name, click the code code icon, then click the Internal name field to enter a new name. To save the name, click Save. Once the property is created, the internal name cannot be updated.
      • Optionally, enter a description for the property in the Description field.
      • Click Next.
      • Select the property type by clicking the Field type dropdown menu, then selecting a field type. By default, the property will be available in forms and bots. To prevent the field from being used in forms and bots, click to clear the Show in forms checkbox.
    • Click Create.

Define the API call

After setting up the event and its properties, you'll need to define the API call to trigger the event. Learn how to define your API call in HubSpot's developer documentation.

You'll need a few pieces of information for your API call, which you can get from inside HubSpot:

  • Event name: the internal name for the event.
  • Property names: the internal names for the properties you'll be sending data to.

To find the internal event name and property names:

  • In your HubSpot account, navigate to Reports > Analytics Tools.
  • Click Custom Behavioral Events.
  • Click the name of the event. You'll then be taken to the event details page.
  • At the top, find the event name under Internal name

    custom-event-internal-name
  • To find the internal names for the properties you'll be updating, click the name of a property.
  • In the right panel, click the code code icon, then view the name under Internal name.

Use custom behavioral event data

Custom behavioral event data can be viewed and used across HubSpot's tools. Below, learn where to view event completions and the ways that you can incorporate that data into other tools.

Report on custom events

Custom behavioral event completions can be analyzed from the custom behavioral events tool, and event data will also be available in the custom report builder and attribution reports.

Learn more about analyzing your custom behavioral events.

View event completions on the contact timeline

Event completions will appear on the contact record timeline, along with any properties that were populated.

To view event details on the contact timeline:

  • Navigate to a contact record that has completed a custom behavioral event.
  • To filter a contact timeline by completed events, click Filter activity, then select Custom behavioral event.

custom-behavioral-events-contact-timeline-filter

  • In the contact timeline, click to expand the event to display the event details.
     custom-behavioral-events-contact-timeline-info

Use custom behavioral events in workflows

In a workflow, you can delay based on custom behavioral event completions using a Delay until event happens action:

  • In your HubSpot account, navigate to Automation > Workflows.
  • Click the name of a workflow. Or, learn how to create a new workflow.
  • In the workflow editor, click the + plus icon to add a workflow action.
  • In the right panel, select Delay until event happens.

workflow-delay-until-event-happens-action

  • Configure the delay:
    • Click the Event dropdown menu, then select a custom behavioral event.
    • Then, select the event property that you want to delay on.
    • Select the filter for the event property.
    • Click Apply filter.

      workflow-delay-until-event-device-type
    • Select the maximum wait time, or select the Delay as long as possible checkbox.
  • Click Save.

The workflow will then delay enrolled records until they meet the specified custom behavioral event criteria.