How to configure webhooks in HubSpot

February 23, 2024

This guide walks you through how to configure webhooks in HubSpot to work with Unified.to. These webhooks allow you to get notifications about new events and changes from HubSpot e.g. new leads, updated deals, or deleted contacts.

Before you begin

• Make sure you have a HubSpot developer account.
• Get your client ID, client secret, and developer API key.
• Point the Redirect URL in your HubSpot app to api.unified.to/oauth/code
  • If you're using the EU data region, use insteadapi-eu.unified.to/oauth/code
• Follow our HubSpot developer guide to see how to do all of the above.

Setting up Webhooks in Hubspot Legacy Apps

Select the appropriate Legacy App to setup the webhook

Set the target URL for the webhook

HubSpot uses a single webhook URL per app, which means you need to configure your app to send any events to the Unified.to servers.

1. Navigate to your HubSpot developer account.
2. Click Apps.
3. Select the app you wish to use to access your customers' data.
4. Click Webhooks.
   
5. Under Target URL:
   1. If you are using the US data region, copy and paste in: api.unified.to/webhook/workspace/hubspot
   2. If you using the EU data region, copy and paste in: api-eu.unified.to/webhook/workspace/hubspot
   
   If your URL is greyed out and you have subscriptions under Event subscriptions, then you'll need to unsubscribe from all of them. WARNING: If these subscriptions and the target URL are used by other applications, this action will break them. In that case, you may want to consider creating a new developer app to use with Unified.to.
6. You do not have to create any subscriptions manually. Unified.to will do that on your behalf.

Add scopes for your webhooks

In order for Unified.to to receive webhook data from HubSpot, you need to add scopes for the events you are interested in as well as a few others.

1. With your app page still open, click Basic Info and then click Auth.
2. Scroll down to Scopes:
   1. Add crm.objects.owners.readas Required.
   2. For any events where you want to read data, add them as Required.
      1. Note: This applies to events that you'll be subscribed to as well as those that you will only call via the API. For example, if you want to create a Contacts webhook and also fetch Companies via the API, you'll need to add both crm.objects.contacts.read and crm.objects.companies.read as Required because Unified.to will pass all of these as required scopes in each auth flow.
   3. For any events where you want to write data, add them as Optional.
   4. For example, if you want to receive notifications about updates to HubSpot companies, you'll need to add crm.objects.companies.read as Required. If you want to write data to companies, add crm.objects.companies.write as Optional.
   5. To see the full list of HubSpot scopes that Unified.to supports, see: https://app.unified.to/integrations/hubspot?tab=oauth2.
3. The oauth scope is also required for all HubSpot integrations. This will be added by default if your app was created after April 2024.
   

Select permission scopes on Unified.to

When prompting your customers to authorize access to their third-party accounts, you will need to select the corresponding scopes in Unified.to as well. The following steps show you how to do that when using our Embedded Authorization component.

1. On app.unified.to, click on Settings and then Embedded Authorization.
2. You will see a preview of the Embedded Authorization component on the left and a list of configuration options on the right. Click on Options.
3. Scroll down to Permission scopes and select webhook as well as any other permission scopes that you need e.g. the same scopes you added in HubSpot. You do not need to select oauth or crm.objects.owners.read on Unified.to as well; Unified maps these automatically.
   1. For example, using the examples from above for reading Contacts and Companies, the scopes in Unified.to would be crm_contact_read and crm_company_read
      
   2. A mapping of Unified scopes to their HubSpot counterparts can be found here.
   3. Tip: Under Integration categories, select CRM to only see scopes related to CRM data objects.

Setting up Webhooks in Hubspot Development Platform

Create Webhook configuration file

In your hubspot project folder, create a new folder webhook and inside add in the webhook-hsmeta.json file.

project-folder/
└── src/
    └── app/
        ├── app-hsmeta.json
        └── webhooks/
            └── webhook-hsmeta.json

Setup Webhook configuration

Now that you have the webhook config file ready, let's setup the configuration as follows:

{
  "uid": "webhooks",
  "type": "webhooks",
  "config": {
    "settings": {
      "targetUrl": "https://api.unified.to/webhook/workspace/hubspot",
      "maxConcurrentRequests": 10
    },
    "subscriptions": {
      "legacyCrmObjects": [
        {
          "subscriptionType": "deals.propertyChange",
          "propertyName": "dealstage",
          "active": true
        },
        {
          "subscriptionType": "deals.associationChange",
          "active": true
        }
      ]
    }
  }
}

For the targetUrl :

1. If you are using the US data region, copy and paste in: api.unified.to/webhook/workspace/hubspot
2. If you using the EU data region, copy and paste in: api-eu.unified.to/webhook/workspace/hubspot

For the subscriptions we need to use the legacyCrmObjects to define which object we want to get events for.

Deploy Hubspot Project

Once you've setup your webhook configuration, you can now upload the project via:

hs project upload

Once uploaded, your configuration should now show up in your app's webhook list:

For creating the webhook in Unified, see How to create and configure webhooks.

See also

• Introduction to webhooks
• Create a webhook subscription
• How to set up your scopes in HubSpot