The Grouparoo Blog

Hubspot Destination

Tagged in Connections Engineering 
By Evan Tahler on 2020-11-06

Grouparoo allows you to connect your Customer and Product data to Hubspot. Grouparoo collects all of your customer data in one place and makes it easy to sync your Profiles and Groups to other marketing tools. Hubspot is a popular email marketing and account management tool with great features and a robust API. However, there are some things to watch out for when integrating with Hubspot that Grouparoo can help with.

How Grouparoo connects to Hubspot

Hubspot setup

In Hubspot, you will need to create a new API Key for Grouparoo to use. Visit Settings -> Integrations -> API Key to generate a new API Key.

Setting the Hubspot API Key

In Grouparoo, Apps provide the credentials to be able to connect to other platforms. For Hubspot, all you need to do is paste in the hapiKey (the h is for Hubspot!) from the Hubspot page. At this point if you hit "Test Connection," you should see "Test Passed" and some data about your Hubspot account.

Configuring the Hubspot App

From there, you can create a Destination and start exporting your Profiles and Groups. You can learn more about creating Destinations here

Implementation Details

One of the values of using an open source customer data platform (CDP) like Grouparoo is that you gain from the experience and attention from multiple companies using the same plugin so it works correctly in the real world.

Grouparoo uses the Hubspot V2 API via the hubspot-api package, in most cases. Here are a few of the things we've learned about using it:

Additional Properties

There are lots of profile properties that can be set on a Hubspot Contact. In order to have a reasonable list of properties in the Grouparoo web interface, we had to make some choices about which properties to show as known properties vs those that we'll hide under the additional properties drop-down. We use the terminology important and unimportant properties. We wanted to make sure that our users could choose to send any property that Hubspot could accept, but to make the setup experience less intimidating. Any profile property you are using is, of course, important, but what about all the others?

Viewing all the Hubspot Profile Properties

We implemented the following heuristics:

  1. If the contact property starts with hs_, mark it as unimportant
  2. If the contact property starts with hubspot_, mark it as unimportant
  3. If the contact property starts with first_, mark it as unimportant
  4. If the contact property starts with recent_, mark it as unimportant
  5. If the contact property starts with num, mark it as unimportant

... you get the idea. You can see how we implemented this our code here.

Interacting with Lists and the Hubspot Legacy API

While the the hubspot-api package package made it very easy to work with contacts, it does not provide any methods for working with Lists. Grouparoo syncs your Groups to what Hubspot calls Static Lists, and we automatically keep those lists up-to-date with the information in Grouparoo.

A Hubspot static list

Luckily, the Hubspot Legacy API makes it very easy to work with lists! We implemented a few methods to create and update lists, and to manage the contacts in them. Hubspot did a great job making their API easy to use.

For example:

  • To enumerate the Lists in your account you GET${hapikey}
  • To create a new list you POST${hapikey} with data={name: groupName}.
  • To add a Contact to a List you POST${listId}/add?hapikey=${hapikey} with data={emails: [email]}

However, things get tricky when you introduce parallelism. The Hubspot API is strictly RESTful, which means if you, for example, try to create a new list twice, one of your API calls will succeed and the other will fail. Grouparoo tries to work as fast as possible when syncing your data. To that end, we'll parallelize exporting profiles to destinations like Hubspot. If we are syncing 2 profiles at the same time, both of which should be in a List that doesn't yet exist in Hubspot, one of those export attempts is likely to run into an issue when creating that list.

To solve this, we needed to introduce a distributed lock across all nodes in the Grouparoo cluster when creating or destroying Hubspot lists. This means that our getLists() method needed a way to "claim" the Hubspot API exclusively from any other process or thread while it checks if a list existed or not. Redis is already part of the Grouparoo infrastructure, and is a great backend for shared locks like this. One process can claim a lock and be certain that they have it, due to the single-threaded atomic nature of Redis. Redis also provides APIs to have locks time out after a certain time if anything goes wrong with the API request, so another process can try again. Redis is also very fast.

In this way, we've been able to continue export data to Hubspot quickly and in parallel, but fall back to "single-threaded" execution for list creation methods that need atomicity.


You can learn more about how to use Grouparoo to send data to Hubspot on our Hubspot Integration Page.

Stay up to date

We will let you know about our launch and new content.

Share this post

Twitter Logo