This blog post is part of our 5-part series about HubSpot API Features. In case you missed Part 4, check it out here!
In this fifth and final installment of our HubSpot API series, we’ll learn how to boost our frontend HubSpot workflows by writing some simple backend code. We’ll be walking you through how to create your own customizable workflow action, allowing you to integrate your workflows with completely disparate services.
And the cherry on top is that it can be built on any HubSpot tier—in other words, you won’t have to upgrade to Ops Hub or another toolset to take advantage.
Why Custom Workflow Actions?
HubSpot workflows are great for setting up behind-the-scenes automations, triggered on some sort of action. Automated email sends, notifications, property changes, and so on are all pretty standard and can be easily configured within the bounds of the frontend workflow tool.
However, you may find yourself needing to integrate your workflow data with an external service or platform, which is likely not doable with the native workflow toolset alone, especially if you don’t have Ops Hub Professional. Maybe you have a custom app that you want to send data to each time a record enters your workflow. Maybe you need the sending of that data to be dynamic, based on the HubSpot record or based on data in your service. Or maybe instead of a homegrown system, you want to integrate your workflow with another software.
Custom workflow actions can handle all of these cases. In a nutshell, code can be written to define an actionable step that can be used within a workflow to send and retrieve data from another service. The key benefit here is that, once defined, you can configure the actual action step on the frontend (aka no further coding).
If that seems abstract, take the HubSpot-Salesforce native integration app for example. Once installed, Salesforce-related workflow actions are also auto-installed on your HubSpot account, allowing you to create Salesforce Tasks or add records to Salesforce Campaigns from HubSpot workflows:
The Task action allows you to create an activity record in your Salesforce environment:
And the Campaigns action allows you to search for, select, and add HubSpot workflow records to an active Campaign object:
In essence, you can create these sorts of custom workflow action definitions to work with whatever service or system is relevant to your use case.
Getting Started with Custom Workflow Actions
It’s always easier to learn something new with a real-life scenario in mind, so we’ll assume the following use case for the duration of this walkthrough:
Let’s say our company hosts several events per year, and for each one, our marketing team puts together a new landing page and webform to capture registrations. We want this data to immediately hit our data warehouse, which stores our disparate system’s information for cohesive, centralized reporting.
Let’s also assume that our IT team spins up a new database table for each event to store HubSpot’s registrant data in. We also want this process to be automated so our marketing and/or IT teams don’t have to manually export and input data.
With these assumptions noted, we’ll create a HubSpot workflow to trigger when a contact submits our event form on our new landing page and create a custom workflow action that will allow the frontend user to find and select the correct database table for the workflow to send data to.
Custom Action Quickstart
Now that we have our use case defined, we can go ahead and start building our app. In order to configure the workflow action, you’ll need to properly create and authenticate a developer app with your target HubSpot account. HubSpot uses the OAuth 2.0 grant type protocol, a specific authorization flow the app must follow. Here’s a detailed walkthrough of this process that you can follow to get the app installed.
With the app set up, we can now define our workflow action. For simplicity’s sake, we’re going to have the user manually enter the table name into the action, but note that with more code, this can be made much more dynamic (take a look at the full HubSpot documentation for a breakdown of all the options).
First, we’ll want to define our action URL – this is where the workflow will send data when it executes. We’ll leverage webhook.site, a website for testing incoming HTTP requests, for initial testing, but ultimately, this would be an endpoint to a service that sits between HubSpot and the data warehouse (we won’t walk through how to build an entire middleware service, but something like a simple Heroku or AWS Lambda instance would work great here).
definition = {
"actionUrl": "https://webhook.site/randomlygeneratedstring"
}
Next, we’ll want to add our field definitions, set the properties we always want to get sent to our service, and define our input labels and action name and description. Putting this all together, our definition object might look something like this:
definition = {
"actionUrl": "https://webhook.site/randomlygeneratedstring",
"objectTypes": [
"CONTACT"
],
"inputFields": [
{
"typeDefinition": {
"name": "staticInput",
"type": "string",
"fieldType": "text"
},
"supportedValueTypes": [
"STATIC_VALUE"
],
"isRequired": True
},
{
"typeDefinition": {
"name": "objectInput",
"type": "string",
"fieldType": "text"
},
"supportedValueTypes": [
"OBJECT_PROPERTY"
],
"isRequired": True
}
],
"objectRequestOptions": {
"properties": [
"email", "firstname", "lastname"
]
},
"labels": {
"en": {
"inputFieldLabels": {
"staticInput": "Database name",
"objectInput": "Additional property to send",
},
"actionName": "Select Data Warehouse Table",
"actionDescription": "Select the data warehouse table to send contact data into",
"appDisplayName": "Send to Data Warehouse",
"actionCardContent": "My Action Card Content"
}
},
"published": True
}
Next, go ahead and POST your definition object to this endpoint:
https://api.hubspot.com/automation/v4/actions/YOUR_APP_ID?hapikey=YOUR_HAPI_KEY
Executing that code should result in a 201 response, indicating that the definition was successfully created and now available in the workflow tool. Let’s confirm by creating a contact-based workflow and opening up the actions menu by clicking on the plus sign underneath the trigger. You should see our custom action appear as an option:
Next, click the action and you’ll be able to type a value in the Database Name field and select which field(s) to send to the table:
Finally, let’s test our action to make sure it sends as expected. Enroll a contact into the workflow and then head on over to your webhook.site page. After a minute or so, you should receive a payload containing values to our defined inputs.
Voilà! And with that, we’ve successfully created and tested a custom workflow action 🥳 – pretty easy, right?
TL;DR
With just a few lines of code, we were able to integrate our workflow with our disparate data warehouse by creating a custom workflow action. Now, our marketing team can easily create a workflow and tell the workflow exactly how to send data to our data warehouse.
Again, we’ve kept things simple and straightforward, but there are tons of options you can add to your definitions to expand functionality. As mentioned, you can construct this action to dynamically pull in table names to display to the user for them to select. You can also create input field dependencies, have the action output data that can be used later in the workflow, or even define serverless functions to transform sent or received payloads. In other words, your actions can get pretty fancy.
Here’s another link to HubSpot’s full API documentation, where you can explore these features in more detail.
If you enjoyed this article, you should check out the first four series installments here. And be sure to check our blog for more tech walkthroughs in the future!
Interested in joining the obo team?
