Integrating Umbraco CMS with HubSpot Forms

Background

This blog post continues the work of the DXP team on providing support and integrations with HubSpot, which started with this package: Integrating Umbraco Forms with HubSpot CRM and delivers in this sequel post a new method that marketers and people using HubSpot can use to take full advantage of the combined benefits offered by the two platforms.

The purpose of this package is to provide a form picker and a rendering component for forms managed through a HubSpot account, using two types of authentication: API key-based or OAuth.

If you want to see it in action, you can reference and use the integration in your own project, as the project is available both on NuGet and on Our Umbraco.

The full source code is open-sourced on GitHub, and you are more than welcome to submit PRs or respond to issues. Credits and a big H5YR go to Frans de Jong and the team of Webwonders who have started the development and kindly donated their work to Umbraco for the extension.

HubSpot Forms Overview

HubSpot is an inbound marketing, sales, and service software, with the Forms component part of the Marketing Hub set of instruments for managing marketing tasks and allowing your team to dedicate time to generating inbound marketing campaigns and getting more leads.

Hubspot is a SaaS (software-as-a-service) solution designed to help businesses grow their web presence with a special emphasis on enabling marketers. The content, lead collection, and analytics are also integrated with the HubSpot CRM, making it easy for marketers to create personalized experiences for visitors and integrate those experiences with the rest of the business.

The HubSpot design system consists of building blocks that can be used to create an environment content creators can work within, with varying degrees of flexibility and guardrails depending on one’s business needs.

To address customer needs worldwide, HubSpot has announced the release of the first regional data center in the European Union. New customers can already use the EU Data Center as of July 2021, while for existing customers the data will be ready for migration in 2022. EMEA () new customers can also take advantage of the new data centers. Read more about this here.

If you want to read more about HubSpot and their hubs and platforms, additional information can be found on their official website.

Working with HubSpot Forms

A form is a group of fields on your website that collects contact information that your customer-facing and marketing teams can use to build deeper relationships.

HubSpot forms integrate directly with your sales, marketing, and customer service efforts to ensure that none of your customer’s valuable information gets lost, and everyone is referencing the same contact data. The information can then be used throughout the HubSpot and Umbraco ecosystems in different areas that cover your day-to-day operations. 

HubSpot Forms are available as client-side embedded scripts, for rendering within your Umbraco website:

Popular features of HubSpot forms include:

• Analytics to understand how your customers interact with your forms
• Customizable calls-to-action to encourage users towards desired behaviors
• Direct integration with Salesforce & HubSpot CRM, making it easy to keep your customer data organized and up-to-date

To read more on how to create forms on HubSpot, you can refer to their knowledge base article here.

Once you have your HubSpot forms created, apart from using them as part of the HubSpot ecosystem, they can be referenced and embedded into content types from Umbraco, by using the custom-built forms picker detailed in this blog post.

OAuth Proxy for Umbraco Integrations

As we strive to build packages that are flexible and extendable, we also have to adapt to all scenarios and to the integration options of the providers we want to showcase. 

The two main authentication options used by a wide range of partners are through

• API key or Access Token, or
• OAuth protocols.

To support OAuth-controlled access, we are using a custom proxy web solution that is intended to act as a security hub between the Umbraco web application and the Authorization Server of the partner we are working with. As detailed in the generic schema below, it will route the OAuth requests to the proper authorization provider, and then send the access details to the initiating entity. To support the various platforms that were integrating, the proxy will receive on every request a header parameter called service_name with a value matching the specific service.

The proxy is hosted here: https://hubspot-forms-auth.umbraco.com/, but you are more than welcome to try it also yourself on your local development environment using the GitHub source code. Umbraco is managing and hosting the solution, but we are open to any questions or related feedback you might have.

Multi-targeting

With the release of Umbraco 9 on .NET 5 and to support package developers migrating their own packages to the new version, Umbraco team has released a step-by-step guide showcasing the migration of the UI Examples package to version 9.

Current HubSpot package follows those guidelines and provides the necessary support for Umbraco 9 also.

Setup and Configuration

As highlighted above, the integration supports two types of authentication, using:

• API key
• OAuth 

In order to validate the authentication workflow, the following protocols are reviewed:

1. Check the settings file (Web.config or appsettings.json) for an API key record. The key will be added to all requests made to the HubSpot API and used to authenticate access.

As highlighted in the above settings, to support HubSpot forms integration for new customers located in EU Data Center, as well as for existing ones, an additional setting will be used for specifying the form location (in the case of  EU, the region will be eu1).

  2. If no API key is present, the OAuth flow will be used using the parameters specified in FormsController.

Data Type & Content Description

Once the package is installed, either through NuGet or from the backoffice, you can go on and register a new data type based on the HubSpot Form Picker:

Immediately after the property editor is selected, the authentication configuration will be validated, and a message displayed to the user in the Settings area. If no API key is present, the Settings area will be slightly different, offering the options to authorize against HubSpot.

• Connect button will load up the HubSpot OAuth authorization window where you will be asked for login credentials and to pick an account attached to your profile. After the authorization is completed successfully, a notification gets prompted and the access token is saved into the database of the Umbraco web application.

• Revoke action will remove the access token from the database and the authorization process will need to be restarted.

After the data type is registered, you can start referencing it across your document type as it will be available in the Pickers section.

Then in your content management area, depending on whether or not you have a valid configuration, you will be prompted with a warning or you will be able to access the forms from your HubSpot account.

The property value converter will generate a strongly typed model which alongside the HTML helper will help you easily render the form on the front-end.

You just need to ensure that your template has a reference to the following using statement:

@using Umbraco.Cms.Integrations.Crm.Hubspot.Helpers;

And you can render the form using (assuming a property based on the created data type with alias hubspotForm has been created):

@Html.RenderHubspotForm(Model.HubspotForm)

Conclusions

On a final note, the integration is open-sourced and the current release targets Umbraco versions 8 and 9.

A minimum set of requirements for the CMS would be:

• Umbraco CMS version 8.5.4 or
• Umbraco CMS version 9.0.1

Feel free to review the custom integrations we are working on in this repository: https://github.com/umbraco/Umbraco.Cms.Integrations, as well as the proxy web application  https://github.com/umbraco/Umbraco.Forms.Integrations. At any point, you can clone those repos on your local development machine and work with them as you please.