Skip to content
Analytics Tools

Create manually tracked custom behavioral events

Last updated: March 10, 2022

Applies to:

Marketing Hub Enterprise

Manually tracked custom behavioral events enable you to define and track events that are unique to your business. Custom behavioral events can be tied to event 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 any custom event properties.
  • Defining 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.
  • 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 you'll use in your API call.

Add and manage event properties

When you create an event, a set of default event properties will be available for you to use. However, 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. Once the property is created, the internal name cannot be updated.

          Please note: property label and internal name are limited to 50 characters.
        • To save the name, click Save
      • 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

  • 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.

Please note: when sending data to your event, keep the following limits in mind:

  • The property label and internal name are limited to 50 characters. 
  • URL and referrer properties can receive up to 1024 characters, while all other properties can receive up to 256 characters.
  • Each event completion can contain data for up to 50 properties.
  • Property internal names must start with a letter and contain only lowercase letters a-z, numbers 0-9, and underscores. Properties with the same internal name after lowercasing are considered duplicates, and only one of the properties will be used on completion.

If these limits are exceeded when making an HTTP API request, the request will fail. If these limits are exceeded when making a JS API request, HubSpot will truncate any property name values to the allowed length and/or update only 50 properties per event completion.

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.


  • In the contact timeline, click to expand the event to display the event details.

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.


  • 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.

    • 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. 

Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.