HubSpot Connector

HubSpot is a Customer Relationship Management software for inbound marketing, sales, and customer service.
Manage contacts, companies, deals, products, engagements, and custom objects in HubSpot.

API Documentation

This component was built using the HubSpot API Documentation currently utilizing v3

Connections

OAuth 2.0

Authenticate requests to HubSpot using OAuth 2.0.

To connect to HubSpot using OAuth 2.0, create an app in the HubSpot developer platform using the HubSpot CLI. An existing legacy app created through the web interface can also be used, though legacy public apps can no longer be created.

Refer to the HubSpot app creation guide and quick reference guide for detailed information.

Creating an App via the CLI

The CLI-based approach is recommended for new HubSpot OAuth integrations as it provides access to the latest features and platform improvements.

Prerequisites

• A HubSpot developer account is required
• Node.js v20 or higher and npm installed (for CLI-based app creation)
• HubSpot CLI version 7.6.0 or higher (installing the latest version is recommended)

Setup Steps

1. Install the HubSpot CLI:

   npm install -g @hubspot/cli
   

2. Authenticate the CLI with a HubSpot developer account:

   hs account auth
   

3. Create a new app project:

   hs project create
   

   • Select App as the project template
   • Choose the distribution type (marketplace or private/specific accounts)
   • Select OAuth as the authentication method
   • Optionally select app features (Card, App Function, Settings, Webhooks, Custom Workflow Action)

4. Configure the app by editing the generated app-hsmeta.json file (located at src/app/app-hsmeta.json within the project directory):

   • Update the name and description fields
   • In the auth section, add https://oauth2.flowbuilder.eu.lansweeper.com/callback for EU sites or https://oauth2.flowbuilder.us.lansweeper.com/callback for US sites to the redirectUrls array
   • Update the requiredScopes array with the OAuth permissions the integration needs. Permissions a user may decline belong in optionalScopes, and those required only for particular features belong in conditionallyRequiredScopes

5. Upload the app project to HubSpot:

   hs project upload
   

   Directory Error

   If the error [ERROR] Unable to locate a project configuration file appears, change to the project folder where the app was created and run the command again.

6. Open the project in the HubSpot developer portal:

   hs project open
   

7. Navigate to the Auth tab in the developer portal

8. Copy the Client ID and Client Secret from the Auth page

Configure the Connection

• Enter the Client ID and Client Secret from the app's Auth page
• For Scopes, choose from the available scopes based on integration needs
  • Refer to the HubSpot scopes reference for scope details

crm.objects.contacts.read crm.objects.contacts.write crm.objects.deals.read crm.objects.deals.write crm.objects.owners.read

Using an Existing Legacy App

An app created before HubSpot's 2025.2 platform release is a legacy app. To use one with this connection:

1. In the HubSpot developer account, navigate to Apps, then click the name of the app
2. Navigate to the app's Auth tab
3. Under Redirect URLs, add https://oauth2.flowbuilder.eu.lansweeper.com/callback for EU sites or https://oauth2.flowbuilder.us.lansweeper.com/callback for US sites
4. Configure the required scopes for the integration in the Scopes section
5. Copy the Client ID, Client Secret, and App ID from the Auth page

Configure the Connection

• Enter the Client ID and Client Secret from the app's Auth page
• Configure scopes as needed (see Recommended Scopes above)

Webhook Support

The App ID and Developer API Key fields are optional and are used only by the webhook actions and the Event Type Subscription trigger. Leave them empty for an integration that does not manage webhook subscriptions.

• App ID appears below the app name in the developer account's Apps dashboard, and on the app's Auth tab
• Developer API Key is available in the developer overview of the HubSpot developer account

App Distribution

HubSpot OAuth apps declare a distribution type that determines who can install the integration and whether a formal HubSpot review is required. Choosing the right one before building the app avoids reworking its configuration and, for a marketplace app, a second review.

The distribution type selected during hs project create determines who can install the app and whether a review process applies.

Private or specific accounts (no review required):
The app is accessible only to HubSpot accounts explicitly added. Users from other HubSpot accounts cannot install it. To add accounts, navigate to the app's Distribution settings in the developer portal and enter each account's hub ID. This is the appropriate option for single-customer integrations or internal tools.

HubSpot App Marketplace (HubSpot review required):
The app is publicly listed in the HubSpot App Marketplace and any HubSpot customer can install it. HubSpot reviews marketplace submissions for quality, security, and functionality before listing.

For integrations deployed to multiple customers, each with their own HubSpot account, the marketplace path is the scalable option. For single-organization deployments, the private/specific accounts path avoids the review process entirely.

This connection uses OAuth 2.0, a common authentication mechanism for integrations.
Read about how OAuth 2.0 works here.

Private App Access Token or Service Key

Authenticate requests to HubSpot using a private app access token or an account service key.

This connection authenticates with either a private app access token or an account service key. Both are entered in the same field and are sent as bearer tokens, so either credential works for every action in this component.

Service keys are HubSpot's recommended credential for new system-to-system integrations. Private app access tokens remain supported for integrations already built against them.

Neither credential expires. A private app access token can be revoked at any time from the HubSpot account settings, and a service key can be rotated or deleted from its details page.

Prerequisites

• Access to a HubSpot account
• A super admin user, which HubSpot requires for access to private apps. A service key can also be created by a user with the Developer tools access permission.

Setup Steps

Follow whichever set of steps matches the credential being used.

##### Create a Service Key

1. Navigate to HubSpot and log in
2. Navigate to Development, then click Keys, then Service keys in the left sidebar menu
3. In the top right, click Create service key
4. Enter a name for the key
5. Click Add new scope, select each scope the integration requires, then click Update
6. Click Create in the top right, then confirm
7. Click the name of the new service key, click Show, then click Copy

##### Create a Legacy Private App Access Token

To generate a private app access token:

1. Navigate to HubSpot and log in
2. Navigate to Development, then click Legacy apps in the left sidebar menu
3. In the top right, click Create legacy app, then select Private in the dialog box
4. On the Basic Info tab, enter a name for the app
5. Click the Scopes tab, click Add new scope, then select each scope the integration requires
6. Click Create app in the top right, then click Continue creating
7. On the app details page, click the Auth tab, click Show token, then click Copy

Configure the Connection

Enter the copied service key or private app access token into Access Token or Service Key.

Webhook Authentication

Authenticate HubSpot webhooks using Client Secret for signature verification only.

The Webhook Authentication connection is used specifically for verifying HubSpot webhook signatures to ensure webhook requests are legitimate.

This connection is only used for webhook triggers and does not grant API access. It solely validates that incoming webhooks are from HubSpot by verifying the request signature.

Prerequisites

• Access to a HubSpot account
• A super admin user, which HubSpot requires for access to private apps
• A HubSpot app configured to deliver webhooks

Both private apps and public apps have a client secret, and HubSpot signs each app's webhook requests with that app's own secret. Use the secret belonging to whichever app delivers the webhooks.

Setup Steps

To copy the client secret from a legacy private app:

1. Navigate to HubSpot and log in
2. Navigate to Development, then click Legacy apps in the left sidebar menu
3. Click the name of the app, or click Create legacy app in the top right and select Private to create one
4. Click the Auth tab
5. Next to Client secret, click Show secret, then copy the value

For a legacy public app, open the app from the Apps dashboard in the HubSpot developer account and copy the Client Secret from its Auth tab.

Configure the Connection

• Enter the Client Secret from the HubSpot app into the connection configuration
• The client secret is used to verify webhook signatures
• Ensure the trigger is configured to use the Webhook Authentication connection

Webhook Subscriptions

After configuring the connection, webhook subscriptions must be set up. In a legacy private app, subscriptions are managed in the app settings and cannot be edited through an API:

1. On the app details page, click the Webhooks tab
2. Under Target URL, enter the URL that HubSpot will send webhook events to (found in the Test Configuration > Trigger Payload section of the integration)
3. Click Create subscription
4. In the right panel, select the object types to subscribe to, then select the events for those objects (for example created, merged, or deleted)
5. If Property changed is selected, also select the properties to watch for changes
6. Click Subscribe

Selecting an object type that needs a scope the app has not authorized prompts for that scope to be added.

Triggers

Event Type Subscription

Receive CRM event notifications from HubSpot. Automatically creates and manages a webhook subscription for selected event types when the instance is deployed, and removes the subscription when the instance is deleted.

New and Updated Custom Records

Retrieves existing and ongoing records for a specified HubSpot custom object type. Load history once, check for changes on a schedule, or both.

New and Updated Records

Retrieves existing and ongoing records for a specified HubSpot object type. Load history once, check for changes on a schedule, or both.

Webhook

Receive and validate webhook requests from HubSpot for manually configured webhook subscriptions.

Actions

Archive Association

Remove the associations between two provided objects.

Archive Batch Contacts

Archive a batch of contacts by ID.

Archive Batch Engagement

Archives a batch of selected engagements by their IDs.

Cancel Import

Cancels an active import.

Create Association

Create an association between the objects identified in the step.

Create Batch Contacts

Create a batch of contacts.

Create Batch Engagement

Creates a batch of selected engagements.

Create Company

Create a new company.

Create Contact

Create a new contact.

Create Custom Object

Creates new custom object schema.

Create Deal

Create a new deal.

Create Engagement

Create a communication, email, call, meeting, note, postal mail or task engagement in HubSpot CRM.

Create Line Item

Create a new line item.

Create Product

Create a new product.

Create Webhook

Create a webhook in HubSpot.

Delete All Instanced Webhooks

Delete all webhooks created by this instance in HubSpot.

Delete Company

Delete an existing company by Id.

Delete Contact

Delete a contact by Id.

Delete Custom Object

Removes custom object schema.

Delete Deal

Delete a deal by its Id.

Delete Engagement

Deletes an engagement by its ID.

Delete Line Item

Delete an existing line item by Id.

Delete Product

Delete a product by Id.

Delete Webhook

Delete a webhook by ID in HubSpot.

Export CRM Data

Begins exporting CRM data for the portal as specified in the request body.

Get Batch Contacts

Read a batch of contacts by internal ID, or unique property values.

Get Company

Retrieve the information or metadata of a company by Id, domain, or name.

Get Contact

Get the information and metadata of a contact by Id or Email.

Get Current User

Return information about the current session's user.

Get Custom Object

Retrieves a specific custom object.

Get Deal

Retrieve information and metadata about a deal by its Id or name.

Get Engagement

Get a communication, email, call, meeting, note, postal mail or task engagement object from HubSpot CRM.

Get Import

Get a complete summary of an import record, including any updates.

Get Line Item

Retrieve the information and metadata of a line item by Id.

Get Product

Retrieve the information and metadata of a product by Id or name.

Import CRM Data

Import CRM records and activities into the HubSpot account, such as contacts, companies, and notes.

List Active Imports

Returns a paged list of active imports for this account.

List Association Types

Retrieve a list of all association types available between two objects.

List Companies

Retrieve a list of all companies.

List Contacts

Retrieve a list of all contacts.

List Custom Objects

Retrieve all custom objects.

List Deals

Retrieve a list of all deals.

List Engagements

List engagement objects from HubSpot CRM, including communications, emails, calls, meetings, notes, postal mail, and tasks.

List Line Items

Retrieve a list of all line items.

List Products

Retrieve a list of all products.

List Properties

Retrieve a list of all configured object properties.

List Webhooks

Retrieve a list of all webhook subscriptions for the HubSpot app.

Raw Request

Send raw HTTP request to HubSpot.

Read Association

Get the Ids of the objects associated with those specified in the step.

Search Deals

Returns a list of deals that match the given properties.

Search Records

Filter, sort, and search objects, records, and engagements across the CRM.

Update Batch Contacts

Update a batch of contacts.

Update Batch Engagement

Updates a batch of selected engagements.

Update Company

Update the information and metadata of an existing company.

Update Contact

Update the information and metadata of an existing contact.

Update Custom Object

Updates an object's schema.

Update Deal

Update the information or metadata of an existing deal.

Update Engagement

Update a communication, email, call, meeting, note, postal mail or task engagement in HubSpot CRM.

Update Line Item

Update the information and metadata of an existing line item.

Update Product

Update the information and metadata of an existing product.

Validate Connection

Returns a boolean value that specifies whether the provided Connection is valid.