Create custom events

Last updated: December 11, 2018

Applies to:

Marketing Hub
Sales Hub

Custom events allow you to track more advanced activity with the JavaScript Events API or Events HTTP API. You'll need to work with a developer to implement the custom event you create into your JavaScript file or server-side script.

  • In your HubSpot account, navigate to Reports > Analytics Tools. Then, select Events.


  • In the upper right, click Create event.
  • In the right pane, enter an Event name, and select Tags (optional) to easily find and keep track of your event. Select Custom event as the Event type.
  • Click Next.

Custom events can be set up in two ways:

JavaScript events

If you're using custom JavaScript to trigger your event, enter the code into the Custom JavaScript field. Any code you enter in this field will automatically be included as part of your HubSpot tracking code. Learn more about using the JavaScript Events API.

After adding your JavaScript, click Save at the bottom right to create your event. You'll be returned to the events dashboard. Hover over the event and click More Edit, then click Next at the bottom right. Here, you'll see the ID that has been generated for the event. Copy and paste the code snippet in the JavaScript callback where you want that event to trigger.

By default, value will be set to null. This is an optional argument that can be used to track the revenue of an event. This value will be used to increment the hs_analytics_revenue property if the event is associated with a contact record. 

Each time the event runs, the value associated with the triggered event will be added to the Revenue field on the contact's record. When setting up the conversion value, you can either enter a specific value or, to dynamically set the value, enter a JavaScript variable or a full jQuery selector. If you're adding a value, ensure you add it to the value parameter before adding the code snippet to your JavaScript file.


If you're using the Events HTTP API, you don't need to enter any JavaScript in the Custom Javascript field.

First, click Save at the bottom right to create your event. You'll be returned to the events dashboard. Hover over the event and click More Edit, then click Next at the bottom right. Here, you'll see the ID that has been generated for the event. You can now use this ID to trigger your custom HubSpot event using an HTTP GET call. 

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

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

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.

Learn more about using the Events HTTP API and adding additional optional parameters.

Other uses for custom events

Tracking Logins to External Site

If you have a login-only section of your external website, you may wish to find out which users are actively logging in. You can use custom events to send this information to HubSpot. Upon login, the event can be triggered and sent to HubSpot. Once saved to the contact's record, you'll be able to segment and create lists based on recent logins filtered by specific time frames, the total number of times the event has been completed, and so on.

Browser and Mobile Usage

You can use custom events to determine which browsers your visitors are most likely to be using and how often they are visiting from a mobile device.

Abandoned Shopping Cart

B2C companies regularly run into the issue of their visitors walking away from their online shopping carts. Whether it's due to a lack of interest or just a brief distraction, sending a gentle reminder can make a difference. If you set up a custom event to trigger once the visitor has calculated shipping, you can then segment contacts using HubSpot lists to see all contacts who have the triggered the event but have not actually purchased.

Custom event limits

You can create up to 2,000 custom events. You will be notified in the events tool if you are approaching your limit.

Once the limit is reached, newly-created events will be added to the Needs approval queue. Approve or dismiss an event by clicking the Needs approval tab, then selecting Approve or Dismiss next to the custom event name. To approve or dismiss in bulk, select the checkboxes left of the events to approve or dismiss and in the header, click Approve or Dismiss.

Events can only be approved if the 2,000 event limit has not been exceeded, and completions will not be counted for events while they are in the approval queue. To recover previously deleted custom events, click the Dismissed events tab. Click Recover next to the event name to restore the event. To recover events in bulk, select the checkboxes left of the events to recover and in the header, click Recover.