Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.useparagon.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Setup Guide

This guide walks you through creating a HubSpot App for testing and development purposes. Once you have finished your integration and are ready to publish in the HubSpot Marketplace for public distribution, jump to Publishing your HubSpot App.

​
Prerequisites

  • Register a HubSpot developer account to associate your app with and to create test accounts.
  • Install and authenticate the HubSpot CLI. If you don’t already have the HubSpot CLI, install it with the following command (requires Node.js):
    Install the HubSpot CLI
    npm install -g @hubspot/cli
    After installation, authenticate your developer account:
    Connect the CLI to your HubSpot account
    hs account auth

​
Creating a HubSpot Project

A HubSpot project is a local package of configuration files defining features of your app like requested OAuth scopes, allowed redirect URLs, and webhooks. You will need to create and upload a project to generate an OAuth Client ID and Secret that we can reference in Paragon.
1

Create a project

Start by creating a project with the CLI using the following command:
hs project create \
  --project-base app \
  --distribution marketplace \
  --auth oauth \
  --features webhooks
We recommend (but do not require) checking this project into version control.
You will be prompted to choose a name and destination for the project.
2

Configure scopes and redirect URL

Open src/app/app-hsmeta.json to update your redirect URLs and scopes:
Add Paragon URL
"redirectUrls": [
- "http://localhost:3000"
+ "http://localhost:3000",
+ "https://passport.useparagon.com/oauth"
],
Paragon default scopes
"requiredScopes": [
  "oauth",
  "crm.lists.read",
  "crm.lists.write",
  "crm.objects.companies.read",
  "crm.objects.companies.write",
  "crm.objects.contacts.read",
  "crm.objects.contacts.write",
  "crm.objects.custom.read",
  "crm.objects.custom.write",
  "crm.objects.deals.read",
  "crm.objects.deals.write",
  "crm.objects.owners.read",
  "crm.schemas.companies.read",
  "crm.schemas.contacts.read",
  "crm.schemas.custom.read",
  "crm.schemas.deals.read",
  "e-commerce",
  "tickets"
],
You can adjust the requiredScopes or optionalScopes to your use case; the only scope required for Paragon is the oauth scope.Learn more about available HubSpot scopes in their documentation.
3

Configure webhooks

If your HubSpot integration does not require webhooks or listening for data changes in Workflows or Triggers, you can skip this step.
Paragon provides a webhook Target URL to subscribe your HubSpot app to events in your users’ HubSpot instances. Copy this URL from the Settings tab of your HubSpot integration in Paragon:
Then, open src/app/webhooks/webhooks-hsmeta.json and add the URL:
Update targetUrl in webhooks-hsmeta.json
"settings": {
- "targetUrl": "https://example.com/webhook",
+ "targetUrl": "https://hermes.useparagon.com/webhook/triggers/...",
  "maxConcurrentRequests": 10
},
Update subscriptions with any specific events that you will subscribe to via Workflows or Triggers. See HubSpot’s webhooks documentation for available subscription types.
4

Upload your project

Upload your HubSpot project to your developer account by saving all changes to project files and running the following command from within the project directory:
hs project upload
Whenever your integration’s HubSpot features change (e.g. different scopes or webhooks), you will need to repeat this step to publish a new version of your HubSpot project.
After it has succeeded, open the project in the developer account:
hs project open
5

Save your OAuth Client ID and Secret

In the HubSpot developer account from the project view, click your app’s name under Project Components and navigate to Auth.
HubSpot projects view
Copy the Client ID and Client Secret values from HubSpot and navigate to Integrations > HubSpot > Configure in the Paragon dashboard to save your OAuth App credentials.
Enter HubSpot scopes in Paragon dashboard
Verify that the list of requested scopes in the App Configuration section of Paragon exactly matches the listed scopes in your HubSpot project.

​
Setup for Legacy Apps

If you are not yet using HubSpot’s project-based framework, follow the below directions to configure your Legacy App in Paragon.

​
Add the Redirect URL to your HubSpot app

Paragon provides a redirect URL to send information to your app. To add the redirect URL to your HubSpot app:
  1. Copy the link under “Redirect URL” in your integration settings in Paragon. The Redirect URL is:
https://passport.useparagon.com/oauth
  1. Log in to your HubSpot developer dashboard.
  2. In Legacy Apps, select the app you’d like to use in Paragon.
  3. Under Auth > Auth settings > Redirect URL, paste in Paragon Connect’s redirect URL found in Step 1.
  1. Select any scopes you’d like to use in your application. Note whether the scopes you permit are required or optional in HubSpot.
Note: crm.schemas.custom.read is a required scope to enable Field Mapping in the Connect Portal.
  1. Press the Save button at the bottom of the page.
HubSpot provides your Client ID and Client Secret needed for the next step.

​
Add your HubSpot app to Paragon

Under Integrations > HubSpot > App Configuration, fill out your credentials from the end of Step 1 in their respective sections:
  • Client ID: Found under Auth > Auth settings > Client ID on your HubSpot App page.
  • Client Secret: Found under Auth > Auth settings > Client secret on your HubSpot App page.
  • Permissions: Select the required scopes you’ve indicated as Required scopes for your HubSpot application.
  • Optional Scopes: Select any optional scopes indicated as Optional scopes in your HubSpot application.
Press the purple “Save Changes” button to save your credentials.
Note: The scopes you specify in Paragon should exactly match the scopes you permitted in your HubSpot application page.

​
Connecting to HubSpot

Once your users have connected their HubSpot account, you can use the Paragon SDK to access the HubSpot API on behalf of connected users. See the HubSpot REST API documentation for their full API reference. Any HubSpot API endpoints can be accessed with the Paragon SDK as shown in this example. 
// You can find your project ID in the Overview tab of any Integration

// Authenticate the user
paragon.authenticate(<ProjectId>, <UserToken>);
             
// List Companies
await paragon.request("hubspot", "/crm/v3/objects/companies", { 
  method: "GET"
});
  
  
// Create Company
await paragon.request("hubspot", "/crm/v3/objects/companies", { 
  method: "POST",
  body: {
    "properties": {
      "city": "Cambridge",
      "domain": "biglytics.net",
      "industry": "Technology",
      "name": "Biglytics",
      "phone": "(877) 929-0687",
      "state": "Massachusetts"
    }
  }
});

​
Building HubSpot workflows

Once your HubSpot account is connected, you can add steps to perform the following actions:
  • Create Record
  • Update Record
  • Get Records
  • Get Record by ID
  • Search Records
  • Delete Record by ID
  • Get Contacts by List ID
You can also use the HubSpot Request step to access any of HubSpot’s API endpoints without the authentication piece. When creating or updating records in HubSpot, you can reference data from previous steps by typing {{ to invoke the variable menu.

​
Working with HubSpot Custom Objects and Custom Fields

It’s common that different HubSpot instances may be configured with different Custom Objects or Custom Fields. Paragon provides the ability for your users to choose their own Custom Object mapping.

​
Custom Object Mapping

To allow your users to choose their own Custom Object Mapping, add the Custom Object Mapping user setting in your Connect Portal Editor. You should give this setting a descriptive user-setting name, for example, if you’re mapping contacts from your app to HubSpot, you might call this “Map Contacts to this object”.
Below, add a label for each object property that should be mapped from your app to a HubSpot object field. In our contacts example, you might add labels for “First Name”, “Last Name”, and “Email”. In your Connect Portal, your users will be prompted to select an object from their HubSpot instance when enabling this workflow. For each of the object properties you labeled, your users will be prompted to select which object field that property should be mapped to. In the workflow editor, you can now access your user’s custom object mapping in the variable menu. For example:

​
Using Webhook Triggers

Webhook triggers can be used to run workflows based on events in your users’ HubSpot account. For example, you might want to trigger a workflow whenever new contacts are created HubSpot to sync your users’ HubSpot contacts to your application in real-time.
You can find the full list of Webhook Triggers for HubSpot below:
  • New Record
  • Record Updated
  • Record Deleted
  • Record Deleted for Privacy (GDPR)

​
Add Webhooks to your HubSpot App

Using HubSpot triggers requires you to add webhooks as a feature to your HubSpot App. To add webhooks to your HubSpot App, follow Setup > Steps 3 and 4 to register Paragon’s webhook URL with HubSpot and subscribe to the event types you are listening for.

​
Webhooks for Legacy Apps

If you are not yet using HubSpot’s project-based framework, follow the instructions below to register Paragon’s Target URL in your Legacy App.
Paragon provides a webhook Target URL to subscribe your HubSpot app to events in your users’ HubSpot instances. To add the target URL to your HubSpot app:
  1. In the Settings tab of your HubSpot integration in Paragon, copy the link under Webhook URL.
  1. Log in to your HubSpot developer dashboard, select your HubSpot developer account, and open your app under Legacy Apps.
  2. In your HubSpot App page sidebar, navigate to Features > Webhooks.
  3. Provide the Target URL. Paragon will automatically begin listening to events on behalf of your app.
  4. Click Save at the bottom of the HubSpot App dashboard.
You are now able to Create subscriptions against the events you want to subscribe to within HubSpot.

​
Publishing your HubSpot App

Required for publishing: In order to list your app on the HubSpot Marketplace, you must implement the following additional features in your integration:For more information, see HubSpot’s documentation on publishing requirements.

​
Setting up Redirect Pages in your app

Your HubSpot App requires a Redirect Page hosted in your application to support an installation flow that begins in the HubSpot Marketplace (i.e., a user searches the HubSpot Marketplace for your app and clicks Install).
For an example implementation of the Redirect Page using React (based on our Next.js sample app), see here.
The Redirect Page should be implemented as follows:
  • Allow X-Frame-Options for hubspot.com.
    • During the installation process, HubSpot will load your Redirect Page URL in a hidden iframe to complete the OAuth exchange.
    • If this is not possible, you will need to use the partner sign-in flow option described here. This will first redirect users to your app directly to begin an installation request (Initial Redirect), rather than using an iframe to complete the installation flow.
  • Import the Paragon SDK and authenticate a user.
    • If the user is not yet logged into your app, we suggest that you redirect to a login form, while preserving the intended URL to redirect to upon successful login. After logging in, your user should see your Redirect Page.
  • Accept and read query parameters, which will be:
    • code: The temporary authorization code to pass to Paragon for completing the OAuth exchange.
    • returnUrl: The URL to redirect to after completing the OAuth exchange.
  • Call paragon.completeInstall to complete the OAuth exchange and save a new connected HubSpot account.
    Complete the OAuth exchange
    const params = new URLSearchParams(window.location.search);

paragon.completeInstall("hubspot", {
  authorizationCode: params.get("code"),
  redirectUrl: "https://your-app.url/hubspot-redirect-page-path"
}).then(() => {
  window.location = params.get("returnUrl");
});

​
Configuring your Redirect Page in your HubSpot App

First, add your production Redirect Page URL to your HubSpot App configuration by modifying your project’s app-hsmeta.json to include it as an authorized redirect URL:
Add Redirect Page URL
"redirectUrls": [
  "http://localhost:3000",
- "https://passport.useparagon.com/oauth"
+ "https://passport.useparagon.com/oauth",
+ "https://your-app.url/hubspot-redirect-page-path"
],
Make sure to publish your changes by uploading a new version of the project:
Update HubSpot App
hs project upload
Next, if you have not already, create an App Listing for your HubSpot Project by navigating to App Listings in your HubSpot developer account. Once viewing your App Listing draft:
  • In Listing Info > Information, select your Redirect Page URL as the Install button URL (you can use a localhost URL while testing a draft).
  • For Sign-in configuration, select “No partner login required, HubSpot OAuth only”.
App Listing draft
You can test your install flow by clicking Preview in the App Listing draft and clicking Install in your preview App Listing page. If your installation succeeds, your Redirect Page is configured correctly!