Create custom behavioral events with the code wizard

Last updated: June 21, 2023

Available with any of the following subscriptions, except where noted:

Custom behavioral events allow 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. Events created with the “Javascript code snippet automatically add event data to your site’s HubSpot tracking code and require someone familiar with Javascript to set up. 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.
Creating a Javascript Code Snippet or 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 custom event.
Select Code Wizard.

Enter an Event name and optionally provide your event description
In the dropdown menu, select your Associated object. This allows you to associate your event completions with different objects in HubSpot, including Contacts, Companies, Deals, and Tickets.

name-custom-behavioral event

Click Next to continue.

Add event properties

When an event is created, default event properties will be available. 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 create properties for an event:

Select the property type by clicking the Field type for your property. Options include:

Custom string property: create a property that is a plain text string.
Custom number property: create a property that is a number value.
Custom timestamp property: create a property that’s a date value. You must send your data in the form of epoch milliseconds or ISO8601.
Custom enumeration property: create a property with a set of predefined values.
When you have selected your property, configure the property in the right panel:

- Enter a name for the property and enter a Description for the property.
- For Enumeration properties, click Next and enter your property Labels and Values. You must set your values and labels before sending data to them. If this step is not completed before sending data that’s not in the list, the data will not be available to use. To send multiple values, separate them with a semicolon.
- Click Done.

- Once your property is created, it will appear in the table under HubSpot’s default event properties. You can edit or delete your property by selecting the Actions dropdown and selecting Edit or Delete.
Click Next.

After setting up the event and its properties, you can either add this event to your website’s tracking code by selecting Javascript code snippet, or send data to HubSpot via API by selecting Send data to HubSpot.

Create a Javascript code snippet

Creating events with a Javascript code snippet allows you to add Javascript to your HubSpot tracking code automatically. This can be used for capturing more complex event data which the tracking code does not capture by default.

Select Javascript code snippet. Use the snippet in the right panel to track the event in HubSpot. Any custom properties created will be predefined within the code snippet.
Modify the snippet as needed by entering text within the right panel. Any code you add will automatically be included as part of your HubSpot tracking code.
When you’re finished, click Create to finish your event and automatically start tracking.

Send data to HubSpot

If you’re sending data to HubSpot, 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 finish creating your event to send data via API:

Select Send data to HubSpot and copy the Tracking ID.
Click Create.

To find the internal event name for an existing event 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, locate 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 icon, then view the name under Internal name.

Please note:
When sending data to your event, the below limits apply:

The property names 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? Yes No

This form is used for documentation feedback only. Learn how to get help with HubSpot.