Create custom events

Custom events allow you to track advanced activity with the JavaScript Events API or Events HTTP API. To implement the custom event you create into your JavaScript file or server-side script, you will require a developer. Once you've created your events, learn how to analyze and manage your event completions.

Create a custom events

• In your HubSpot account, navigate to Reports > Analytics Tools.
• Click Events.
• In the upper right, click Manage events.
• In the upper right, click Create event.
• In the right panel, set up your event:
  • Enter an Event name.
  • To easily find and keep track of your event, you can click the Tags dropdown menu and select or enter a tag.
  • In the Event type section, select Custom event.
• Click Next.

• The next step depends on the API you're using to trigger the event: JavaScript Events API or Events HTTP API. The following sections cover details on creating the event for these APIs.

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 the JavaScript Events API.
• After adding your JavaScript, click Save to create your event.
• You'll be redirected to the events dashboard. Hover over the event and click the More dropdown menu, then select Edit.
• At the bottom right, click Next.
• 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.

HTTP API Events

• If you're using the Events HTTP API, you don't need to enter any JavaScript in the Custom Javascript field. Click Save to create your event.
• You'll be redirected to the events dashboard. Hover over the event and click the More dropdown menu, then select Edit.
• Click Next to view 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 is automatically generated, containing the following required parameters:

• _n: the Event ID of the event.
• _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.

Possible uses for custom events

Tracking logins to external site

If you have a login-only section of your external website, you can use custom events to send to HubSpot information which users are actively logging in. Upon login, trigger the custom event. Once saved to the contact's record, you'll be able to segment and create lists based on recent logins. Some filters you can opt to use are specific time frames and the total number of times the event has been completed.

Browser and mobile usage

You can use custom events to determine the browsers your visitors frequently use and how often they visit from a mobile device.

Abandoned shopping cart

Visitors frequently do not complete onlines purchase on a B2C company's website. Set up a custom event trigger once the visitor has calculated shipping, then segment these contacts in a list. Use the list to send a reminder to the contacts to finish their purchase.

Custom event limits

Once the limit is reached, newly-created events will be added as Unexpected events in your events manager. To access your events manager:

• In your HubSpot account, navigate to Reports > Analytics Tools.
• Select Events.
• In the upper right, click Manage events.
• To approve or dismiss an event, in the left sidebar menu, click Unexpected events.
• Next to the custom event name, select Approve or Dismiss.
• To approve or dismiss in bulk:
  • Select the checkboxes left of the events to approve or dismiss.
  • At the top of the table, 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:

• In the left sidebar menu, click Rejected.
• Hover over the event to restore and click the Actions dropdown menu, then select Recover.
• To recover events in bulk:
  • Select the checkboxes to the left of the events to recover.
  • At the top of the table, click Recover.