Using Custom Events

Last updated: December 19, 2016

Available For:

Product: HubSpot Marketing
Subscription: Enterprise
Custom Events allow you to track just about any type of interaction that a user can make with your website.

Please note: Events are only available in the Enterprise edition of HubSpot. Both Professional and Enterprise accounts have the ability to create lists based on visited URL, but only Enterprise can create a visited URL event report.

Why use Custom Events?

You may be thinking, "but what if I need to track something that is more advanced than the types you discussed earlier in the guide?” We had the exact same thought, which is why we created Custom Events.

When creating a Custom Event, you have two options:

  • JavaScript Event
  • HTTP API Event


The following instructions go over the required steps to set up a Custom Event in HubSpot. You will still need to work with a developer to implement the event you create into your Javascript file or server-side script.

Navigate to Events

From your HubSpot Dashboard, navigate to Reports > Events.

HubSpot Help article screenshot

Create a new Event

On the right, select the blue Create new event button.

HubSpot Help article screenshot

Create a custom event

When selecting Track type of event, select Custom Event.

This is the point where you need to choose between creating a JavaScript event or a HTTP API event.

HubSpot Help article screenshot

JavaScript Events

Click on the Add Custom JavaScript link. This will open up the area where you can add your custom JavaScript code. When the HubSpot Tracking Code is executed on your internal or external pages, this JavaScript snippet will be queued up via the variable _hsq.

If you only want this event to be triggered on a specific page, add the URL to the URL (optional) box.

Update the first line of the automatically generated code in the editor to if (true) or remove that rule all together to have the event fire on every tracked page load.

Once you save your event, HubSpot will generate an id for that event. You can paste that snippet of code within the Javascript callback where you want that event to trigger. Please note that you do not need to update your HubSpot tracking code or manually add any code to your page when an event is created; the JavaScript is automatically included in the tracking code. By default, value will be set to null, but if you would like to associate a conversion value to record in the revenue contact property, you can enter a number. You can learn more about using value here.

When the page is loaded and our JavaScript is executed, we create a variable _hsq which acts as a queue that you can push tracking events onto. You can add events to be tracked before our JavaScript is loaded by setting the variable _hsq to an array and filling it with event calls.

For more information about custom JavaScript events, please refer to our Developers' forum.


When creating a HTTP API Event, a URL will be automatically generated containing the following necessary parameters:

  • _n - the Event_ID of the event you are recording
  • _a - your HubSpot ID

Next, you need to name and save your new event.

In order to successfully connect a triggered HTTP API Event to a contact record in HubSpot, you need to pass the contact’s email address, &email, in the request URL. If a contact record does not yet exist for this email address, a new record will be created. Otherwise, the event will be attributed to the existing contact.

Two other useful parameters that can be used are the _m and property parameters. Add &_m to the Request URL to add a value to a contact’s Revenue field and &property to the Request URL to set a contact property. This new property information will overwrite a null value, but will not update a property that already contains a value.

For example, here is a test URL to trigger an event:

Lastly, to trigger the HTTP API Event, you must make a request to our tracking API with the path /v1/ element.

For more information about HTTP API Events, refer to our Developers' forum.

HubSpot Help article screenshot

Previous article:

Next article: