Connectors / Service / Hubspot

Hubspot

Hubspot

A full platform of marketing, sales, customer service, and CRM software

Overview

IMPORTANT!: Note that v5.x is currently going through an internal upgrade to include all desired Hubspot operations. If the latest version does not have the operation you need please use either the Raw Http Request operation, or v3.11 of the Hubspot connector.

HubSpot offers a full stack of software for marketing, sales, and customer service, with a CRM at its core. They can be used independently or together.

Authentication

When using the Hubspot connector, the first thing you will need to do is go to your Tray.io account page, and select the workflow you wish to work on. Once in the workflow builder itself, search and drag the Hubspot connector from the connectors panel (on the left hand side) onto your workflow.

With the new Hubspot connector step highlighted, in the properties panel on the right, click on 'New Authentication' which is located under the 'Settings' heading.

This will result in a Tray.io authentication pop-up window. The first page will ask you to name your authentication, and state which type of authentication you wish to create ('Personal' or 'Organisational').

set the scopes that are required to access your account and interact with the relevant data sets:

As you can see, the next page asks you to set up the scopes required for your individual project. Note that the scopes required will depend on the specific user/ app/ portal setup of your account. So, for example, if you tick the 'hubdb' box then the user you are authenticating with must have access to a portal with the HubDB tool. A helpful discussion thread on authentication scopes is found

here

So before going further make sure you have only ticked the scope boxes which your account has access to and which are required for the operations you want to carry out.

Once you have added these scopes to your Tray.io authentication popup window, click on the 'Create authentication' button. Go back to your settings authentication field (within the workflow builder properties panel), and select the recently added authentication from the dropdown options now available.

Your connector authentication setup should now be complete.

Hubspot Trigger

If you wish your workflow to be kicked off by a particular action in Hubspot, you can use the Hubspot Trigger.

The Hubspot trigger allows you to receive notifications and trigger workflows when given events occur associated with the selected trigger operation.

Trigger Operations available:

  • Webhook

Webhook Setup

When creating a new workflow, click the 'Create new workflow' button in the top right hand corner of your main Tray.io dashboard. When the trigger popup window opens, search and select the Hubspot trigger. Wait to be redirected to your new workflow and the workflow dashboard itself.

Version 3.0+

1. Select which event types you want the workflow to trigger for. This is done by checking the relevant boxes from within the input panel.

2. Select an authentication associated with the Hubspot account you wish to receive notifications for or create a new authentication as detailed in the Authentication section of this page.

3. Finally, enable your workflow by selecting the Enable button in the right hand corner of the workflow. The workflow will now trigger when relevant events occur.

Version 2.0 and earlier

1. Now click on the settings dots in the top left of the workflow editor:

You can then copy your workflow webhook url:

Make sure to enable your workflow before going any further, otherwise your webhook will fail

2. Now go to your Hubspot app developer page at e.g. https://app.hubspot.com/developer/23xxxxx99.

PLEASE NOTE: To know more about how to create a developer account and an app in Hubspot, refer to the documentation on How do I create an app in HubSpot?

3. Click on the app you wish to receive updates from and then on 'Webhook subscriptions' before entering the webhook url (retreived in step 1) into the Target URL box:

4. Click on Create Subscription to set up an event trigger:

As you can see, it is possible to fine tune the update event. The above example shows how you can trigger the webhook only if the hubspotscore for a contact is updated.

5. Once you have created the subscription you will see the test webhook page:

Here you can enter the webhook url (from step 1) again and click Test to send a sample payload to your workflow.

6. Remember from Step 1 to check that your workflow is enabled. Then click on the Debug tab to look at the logs and you should see the payload from the webhook test:

In a live Workflow environment you could extract data from the webhook payload according to our basic working with data guide and pass it on to other Connectors by using a json path such as $.steps.trigger.body.propertyValue.

Note on operations usage

Updating contacts

It is important to note that the Update contact operation is not an 'upsert' operation.

'Upsert' means an update operation which will either update a contact which matches a certain id, or create a new one if no match is found.

So, in this case, because Update contact does not support this, you will need to first use a boolean connector to check if a contact exists before attempting to create or update them yourself without the automatic assistance of an upsert operation.

The first example below will take you through how to do this.

Setting fallback values

A particular issue with the Hubspot API is that, if a field for e.g. a contact, has no value then it will not be returned at all in the results.

This presents a problem if you are wanting to update another service or database which is expecting either a result or a fallback value such as an empty string or a string such as 'not found' etc.

The second example below shows how you might deal with this with a simple script.

Example - create / update contact

PLEASE NOTE: Some of the operations used in this example are currently only available in version "3" of the Hubspot connector. So please revert to v3.11 to make use of this functionality, or make use of the Raw Http Request operation.

The above workflow imagines a scenario whereby your workflow has been kicked off by a webhook from a third-party service which indicates an update is required to a contact in Hubspot

The first step is to pull the email from the trigger and use the Find contact by email operation:

Then Contact exists checks whether the result of this is true or false:

Create contact if not found

If it is false then the contact must be created

In this example we format the date to be passed, before using the Create contact operation:

Update contact if found

If it is true then we can update the existing contact with the Update contact operation.

The key point here is that we use the $.steps.hubspot-1.contact.vid jsonpath to use the vid returned by the Find contact step:

Example - set fallback values

PLEASE NOTE: Some of the operations used in this example are currently only available in version "3" of the Hubspot connector. So please revert to v3.11 to make use of this functionality, or make use of the Raw Http Request operation.

In the above example we have made a Find Contact by ID call to Hubspot.

Before feeding into another service or database, the pieces of customer data we are wanting to receive from this are:

  • email
  • phone
  • companyName

We must have a value for each, even it is an empty string.

Because Hubspot will not return a field which has no value, we must use a Compile input script

This uses the properties from the previous Hubspot step to set the customer data as a 'customer' variable that can be used in a script:

Variables used as inputs in a script step can be called anything you want - customer, company, deal etc. - depending on what you call the entity you are dealing with

The script then uses input.customer (or input.deal, input.company etc.) and can make use of the javascript _.get operation:

exports.step = function(input) {
let result = {
email: _.get(input.customer, "email.value", "not found"),
phone: _.get(input.customer, "phone.value", "not found"),
companyName: _.get(input.customer, "company.value", "not found")
};
return result;
};

An example output of this would be:

You could change the script if you want to return empty strings instead of 'not found':

exports.step = function(input) {
let result = {
email: _.get(input.customer, "email.value", ""),
phone: _.get(input.customer, "phone.value", ""),
companyName: _.get(input.customer, "company.value", "")
};
return result;
};

Which would return:

The result of either approach is that you will now be able to use a jsonpath such as $.steps.script-1.result.phone to use the empty string or 'not found' information to any subsequent steps which feed the reults into another service or database.

Example - List Contacts and Find Contact by ID

PLEASE NOTE: Some of the operations used in this example are currently only available in version "3" of the Hubspot connector. So please revert to v3.11 to make use of this functionality, or make use of the Raw Http Request operation.

Create a new workflow with a Manual Trigger, a Hubspot connector, a Loop Collection and a second Hubspot connector:

For the first Hubspot connector, authenticate as above and choose the List Contacts operation.

If you were to run the finished workflow, the log from a successful output would show that this operation returns an array of contacts objects:

Then set the Loop Collection connector to Loop List and enter $.steps.hubspot-1.contacts as the List in order to grab the above contacts one-by-one:

You will note from the above output that vid is an output field. So you can then, for each contact that is fed by the loop, grab the vid for the second Hubspot connector:

The Find contact by ID operation is chosen and $.steps.loop-1.value.vid gets the vid of the contact from the Loop connector to enter it as the Contact ID to pull the contact from Hubspot.

Once the workflow is set up, click 'Run Workflow Now' and then click on the Debug tab to look through all the inputs and outputs of a successful run of the workflow:

Example - Create and update engagement

PLEASE NOTE: Some of the operations used in this example are currently only available in version "3" of the Hubspot connector. So please revert to v3.11 to make use of this functionality, or make use of the Raw Http Request operation.

Create engagement

There are 5 types of engagement activity in Hubspot, Note, Email, Task, Meeting, and Call. The properties for each type is different. To create an engagement, the type needs to be selected from the dropdown. When updating an engagement, the type needs to be known beforehand. This can be obtained from the Get engagement operation.

In this example we'll create a Call engagement, linking it to a contact within Hubspot.

The input is split into 3 areas, Engagement details, Metadata and Associations. Engagement details are fields that apply to all engagement types, currently these are owner and the timestamp of when the engagement activity occurred.

Metadata consists of the type specific properties for the engagement. In this example, we can see the Call properties consists of From number, To number, Duration, Recording URL and Body (call notes).

The associations allow you to link the engagement to a contact, company or deal. Doing this makes the engagement appear on that particular contact/company view in the Hubspot account UI.

Update engagement

To update an engagement, two things are required, the engagement ID and the type of the engagement (so the correct metadata properties can be chosen).

Important: the correct metadata option must be selected even if not updating any metadata properties e.g. if only updating owner ID.

If not updating any metadata, ensure you are setting the fields to <no value> and not touching the drop downs to ensure no data gets overwritten with empty strings.

All Operations

Latest version:

5.3