Connect to HubSpot

This article provides instructions on the steps required from you (the vendor) to integrate 10Duke Scale with HubSpot using HubSpot webhook events and a HubSpot connected app. See information on webhooks and private apps in HubSpot’s documentation.

When you create customers, deals (one-time deals or subscriptions), line items, and license grants in the HubSpot UI, HubSpot generates and sends events to 10Duke Scale, which then triggers the corresponding actions.

The following actions are supported:

Set up and update your B2B customers
Grant and update licenses for one-time deals
Grant and update licenses for subscriptions
Delete licenses

The integration requires an optional 10Duke Integration Service component that is purchased separately.

Contact 10Duke to get started with the integration and get support with the setup needed in HubSpot.

The integration also requires setup and configuration changes in 10Duke Scale, which are handled by 10Duke.

Supported actions

See the following sections for information on the supported actions.

See also detailed information in HubSpot’s documentation on creating companies, contacts, deals, properties, custom objects as well as deleting deals and line items.

Webhook events

When you create companies, deals, and line items in the HubSpot UI, HubSpot sends webhook events for the created objects (such as a Company or Deal object), which then trigger actions in 10Duke Scale. By default, HubSpot attempts to deliver each webhook event up to 10 times. We recommend keeping this default value unchanged.

Data retrieval for Company and Contact objects

The 10Duke Integration Service retrieves Company and Contact object data for records created in HubSpot before the deployment of the 10Duke Integration Service.

The data is retrieved based on Company and Contact creation and update events as follows:

The Company and Contact data are retrieved when an update event is received for a company or contact that does not yet exist in 10Duke Integration Service.
If the related Company data also does not exist in the 10Duke Integration Service when a Contact creation or update event is received, the Company data is retrieved provided that the Contact object is associated with a Company object in HubSpot.
If Contact data does not exist in 10Duke Integration Service when a Contact update event is received, the Contact data is retrieved. If the Company data does not exist in 10Duke Integration Service when the Contact update event is received, the Company data is also retrieved if the Contact object is associated with the Company object in HubSpot.

Although data for both Company and Contact object records is retrieved, no customer is created in 10Duke Scale until the related Contact data is available for the Company. Customer creation in 10Duke Scale is dependent on the availability of the Contact data and is only triggered after a Contact record has been successfully retrieved and processed.

As a result:

The 10Duke Integration Service retrieves Company and Contact data.
If neither the lifecycle stage configuration nor the configuration for selecting a specific contact as the B2B customer’s contact is used, the Company results in a visible customer in 10Duke Scale once the corresponding Contact data has been successfully processed and associated with the Company object.
If the lifecycle stage configuration and the configuration for selecting a specific contact as the B2B customer’s contact are used, the Company does not result in a visible customer in 10Duke Scale until the value that triggers the customer contact creation is set and the corresponding Contact data has been successfully processed and associated with the Company object, and the lifecycle stage that triggers the customer creation in 10Duke Scale is set to one of the configured values.

Custom license grant object

The 10Duke Integration Service supports the use of a custom “license grant” object in HubSpot, which stores the information required for granting licenses for both one-time deals and subscriptions.

Note: The use of custom objects requires the HubSpot Enterprise subscription.

A custom license grant object contains information on a single product configuration used for granting licenses. One or more license grants can be associated with the standard HubSpot object Company.

When using a custom license grant object, HubSpot configuration is only required for the Company, Contact, and License Grant objects.

See how to set up the custom license grant object in HubSpot.

Create a company

When a company is created for a customer in HubSpot, HubSpot sends create events that trigger the following actions in 10Duke Scale:

A customer is created, and a default license container to hold the customer’s licenses.

Note though that if the email address provided for the customer already exists for a customer in 10Duke Scale, no new customer is created.

Note: Although you can add multiple contacts to a company in HubSpot, the 10Duke Integration Service only processes the first valid contact and creates a user account for that contact in 10Duke Scale.

See more information on customers, license containers, and license consumers in 10Duke Scale.

Optionally, customer creation in 10Duke Scale can be configured to trigger only for specific HubSpot company lifecycle stages. This allows you to, for example, create a HubSpot company for a potential lead early on, while delaying the customer creation in 10Duke Scale until the customer relationship has been established.

You can also optionally configure a specific contact to be selected as the customer’s contact in 10Duke Scale. This configuration is triggered only when a specific value is set in the Tenduke Type custom property in HubSpot during contact creation.

To ensure the integration receives all required information, complete each step below in HubSpot.

Note: Missing or incomplete information prevents customer creation in 10Duke Scale.

To create a company for a B2B customer in HubSpot:

Provide a company name. This is set as the name of the customer in 10Duke Scale.
While creating the company, add an association between the Company and Contact objects before saving.

Note: If you do not associate the contact during the initial creation, you can do it later, but you must add the contact before all other required fields are fulfilled. However, if needed, you can make subsequent changes to the company after it has been created, which will retrigger the creation of the organization in 10Duke Scale.

Create a contact by providing at least the following details:
- Last name
- Email address (must be unique across all 10Duke Scale users)
- Phone number (optional)
- Tenduke Type
  
  If the configuration for selecting a specific contact as the B2B customer’s contact in 10Duke Scale is in use, select the Tenduke Type value that will be used to trigger the contact creation.
  
  Note that if the configured Tenduke Type value is not selected for the contact, or the contact is not linked to the company, the customer is not created in 10Duke Scale. The company is created only when the contact is linked to the company and the configured Tenduke Type value is present.
The email is set as the email address of the customer in 10Duke Scale. Note that you need to enter the contact’s last name in HubSpot when creating the contact, but the last name is not used in 10Duke Scale.
If the lifecycle stage configuration is in use, select a suitable lifecycle stage for the customer. The value used for this is stored in the Internal name field in HubSpot.

If the selected lifecycle stage is included in the configuration, the customer is created in 10Duke Scale.

If you select any other lifecycle stage, customer creation is triggered later when you update the company to use one of the configured lifecycle stage values.

Update a company

When a company is updated in HubSpot, HubSpot sends update events that can trigger the following actions in 10Duke Scale:

If the optional lifecycle stage configuration is in use, the update can trigger the first-time creation of the customer in 10Duke Scale (see more on company creation).

This happens if customer creation hasn’t been triggered yet for the HubSpot company, and you change the company to use one of the configured lifecycle stage values.

Important: While the company only exists in HubSpot, you can modify the company and contact data there as needed. Once the customer creation criteria is met and customer creation is triggered in 10Duke Scale, the user account is created using the contact associated with that creation event (for example, the contact marked with the Tenduke Type value that triggers the admin user creation). The email address used for the 10Duke Scale user account is taken from that contact’s current email address in HubSpot.

If a company has multiple contacts, ensure that the intended B2B customer’s contact is configured correctly before triggering customer creation. Any subsequent contacts on the company are ignored and no user account is created from them.

If the lifecycle stage configuration is in use, note that changing the lifecycle stage back to a value that is not included in the configuration doesn’t revert the customer creation in 10Duke Scale. Changes to the lifecycle stage are ignored by the integration at this stage.

Grant licenses

When a deal (a one-time deal or a subscription) is created for a registered customer in HubSpot, HubSpot sends create events that trigger the issuing of new licenses to the B2B customer in their default license container.

The event specifies one or more SKUs in HubSpot products, which map to 10Duke Scale product configurations used for issuing the licenses.

For granting licenses, you can use either line item objects or a custom license grant object. Whichever method you choose, ensure that all information required for the integration is correctly entered into HubSpot.

Grant licenses using line item objects

Create a deal in HubSpot for the appropriate company.

(To be able to proceed, the HubSpot UI requires you to define a product and a quantity. These settings are not used by the integration.)
Add the line items to the deal.

For each line item object, define the data required by the integration:
- Deal: The deal ID is prefilled if you are creating the line item object within the deal. Otherwise, select the correct deal.
- SKU: This must match the name of the product configuration in 10Duke Scale that is used for granting the licenses.
  
  If the Product Code custom property is in use, it defines the product configuration in 10Duke Scale instead of SKU.
- Term: The length of the license validity. It defines the type of license created in 10Duke Scale:
  - If the term is empty, a subscription license is created.
  - If the term has a value, a one-time deal is created.
- Quantity: The quantity of the licenses with the same product code, for example, the seat count.
If the deal stage configuration is in use, select a suitable deal stage for the deal.

If the selected deal stage is included in the configuration, the licenses will be granted in 10Duke Scale.

If you select any other deal stage, the issuing of the new licenses is triggered later when you update the deal to use one of the configured deal stage values.
When you have defined all the necessary line items with the correct values, you can create the deal. The licenses will take effect based on the following criteria, in order:
- The value in the License start date custom field in the HubSpot UI.
- The instant the Deal object enters the Closed Won stage in HubSpot, or another HubSpot deal stage if the deal stage configuration is in use in 10Duke Scale.
- The Close date value in the HubSpot UI.

After completing a deal, don’t add any new line items.

Grant licenses using custom license grant objects

Add the license grants.

For each license grant, define the data required by the integration:
- Product ID: The ID of the product configuration in 10Duke Scale that is used for granting the licenses.
- Product Code: When Product ID is not provided, the Product Code is used instead. Define the name of the product configuration in 10Duke Scale that is used for granting the licenses.
- Quantity: The quantity granted in a license, if the associated configuration has license consumption set to enforced. If the quantity type is seats, the maximum quantity is 1000.
- Company ID: The customer in 10Duke Scale that grants the licenses.
- Start Date: The start date of the license validity.
- End Date (optional): The end date of the license validity. An empty value means granting perpetual licenses.
Save the data.

The licenses will take effect immediately.

Update licenses

Updating a license grant requires providing the same information in HubSpot as when granting licenses.

Note the following:

If you change SKU in a line item, or Product ID or Product Code in a license grant to point to another product configuration, you effectively replace the old licenses with new licenses for the other product.
As a general rule, we recommend that you don’t change the Term for a line item object, as this has no effect on licenses in 10Duke Scale. The only use case where you can change it is when changing also SKU, in which case it will be used as a start date for the new licenses created with the new product configuration.

Delete licenses

If you delete a line item from a deal (a one-time deal or a subscription) or a license grant object in HubSpot, HubSpot sends a delete event that triggers the deletion of the licenses associated with the line item or license grant object in 10Duke Scale.

In the same way, if you delete the whole deal in HubSpot, HubSpot sends a delete event that triggers the deletion of all the licenses associated with the deal’s line items in 10Duke Scale.

Limitations

With B2B customers’ subscriptions, note that if you move granted licenses to other license containers, updating a subscription’s licenses may affect how the customers’ license consumers can access those licenses in 10Duke Scale. See more information on granting access to licenses.

Setup in HubSpot

Complete the steps below for the integration setup in HubSpot. The setup consists of creating a connected app in HubSpot to connect HubSpot to 10Duke Scale.

Step 1: Create a custom property for the Contact object (optional)

If the configuration for selecting a specific contact as the B2B customer’s contact in 10Duke Scale is in use, create a new custom property for the Contact object in HubSpot.

Navigate to your HubSpot account.
Click the settings icon.
Go to Data Management > Properties.
Click Create property.
Add the property details:
- Property label: Tenduke Type
- Internal name: tenduke_type
Set the field type of the custom property to Single-line text.
Click Create.

Step 2: Create a custom property for the Line Item object (optional)

If product codes need to be used for defining the product configuration in 10Duke Scale, create a new custom property for the Line item object in HubSpot.

Navigate to your HubSpot account.
Click the settings icon.
Go to Data Management > Properties.
First, create the new custom property.
1. Click Create property.
2. Add the property details:
  - Property label: Product Code
  - Internal name: product_code
  - Object type: Product
  - Group: Product information
3. Set the field type of the custom property to Single-line text.
4. Click Create.
Next, add the created custom property to the Create product form.
1. Go to Products > Data Management > Products > Customize the ‘Create product’ form.
2. Drag the product code field to the form.
3. Save the form.

Step 3: Define the basic information for the connected app

Navigate to your HubSpot account.
In HubSpot’s account management, go to integrations > private apps and create a new private app.
In the basic information, define a unique name for the connected app.

Step 4: Select the scopes for the connected app

In the scopes, select the scopes required by the integration:
- crm.objects.companies.read
- crm.objects.contacts.read
- crm.objects.deals.read
- crm.objects.line_items.read

Step 5: Create the webhook subscriptions for the connected app

Before you start:

You need the 10Duke Integration Service API URL for receiving webhooks. Contact 10Duke to get the URL.

In the webhooks, enter the 10Duke Integration Service API URL.
For each object type, create a new webhook subscription.
- For the Deal object event subscription:
  - Select the event to be listened: Association changed, Created, and Property changed
  - Select the required properties: closedate and dealname
    
    If the deal stage configuration is in use in 10Duke Scale, select also the dealstage property.
- For the Contact object event subscription:
  - Select the events to be listened: Created and Property changed
  - Select the required properties: email, firstname, lastname, and phone
    
    If the configuration for selecting a specific contact as the B2B customer’s contact is in use in 10Duke Scale, select also the tenduke_type property.
- For the Company object event subscription:
  - Select the events to be listened: Association changed, Created, and Property changed
  - Select the required properties: address, city, hs_country_code, state, name, and zip
    
    If the lifecycle stage configuration is in use in 10Duke Scale, select also the lifecyclestage property.
- For the Line item object event subscription:
  - Select the events to be listened: Created, Deleted, Association changed, and Property changed
  - Select the required properties: hs_sku, name, quantity, and hs_recurring_billing_period
    
    If the Product Code custom property is used, make sure to select the product_code property instead of the hs_sku property.
    
    Note: Selecting the incorrect property can lead to errors in license provisioning.
Make sure all information has been correctly entered and create the connected app.

Creating the connected app generates a client secret required for webhook signature validation and an access token required for authenticating API calls from 10Duke Scale to HubSpot.
Find the client secret and access token for the created HubSpot private app in the app settings for authentication.
Share the secret and access token with 10Duke in a secure manner for setting up your configuration for the integration service.

Step 6: Create the custom license grant object (optional)

If you use a custom license grant object for granting licenses, create the custom object in HubSpot.

To create the custom license grant object:

In your HubSpot account, go to Data Management > Objects.
Click Create a custom object.
In the right panel, set up your custom object:
- Enter the object name in singular and plural: License grant and License grants.
- Create the primary display property for the custom license grant object.
  - If the product ID is used for granting licenses:
    - Define the name of the property: Product Id.
    - Set the property type to Single-line text.
    - Click the pen icon below the name, edit the property’s API name to productid and save.
  - If the product code is used for granting licenses:
    - Define the name of the property: Product Code.
    - Set the property type to Single-line text.
    - Click the pen icon below the name, edit the property’s API name to productcode and save.
- Create the secondary display properties with the following names, property types, and API names:
  - Quantity:
    - Secondary display property: Quantity
    - Property type: Number
    - Internal name: quantity
  - Valid From:
    - Secondary display property: Valid From
    - Property type: Date picker
    - Internal name: validfrom
  - Valid Until:
    - Secondary display property: Valid Until
    - Property type: Date picker
    - Internal name: validuntil
- Click Create.
Define the custom license grant object’s associations.
- Go to Settings > Objects.
- Select the created custom license grant object.
- In Associations, click Go to data model builder.
- Configure the association limits.
  - For License grant-to-Companies, select the Custom option and set the limit to 1.
  - For Company-to-License grants, select the Many License grants option.
- Save the association limits.
Customize the License Grant form.

In Settings > Objects, edit the License Grant form.
In the configuration wizard, select the properties that need to appear in the form.
Make the Quantity and Valid From properties required.
Make the Company association required.
Save the changes.

Update the scopes and webhooks in your connected app.
- Go to your connected app > Webhooks.
- Click Edit app.
- In Scopes, add the following new scopes:
  - crm.objects.custom.read
- Click Update.
- In Webhooks, add the following new webhook subscriptions for the created custom license grant object. Note that using the expanded object support (BETA) is required for creating a webhook subscription for custom objects.
  - Select the object type: License grant
  - Select the events to be listened: Created, Deleted, and Property changed.
  - Select the required properties: productid, productcode, quantity, validfrom, and validuntil.
  - Click Subscribe.
- Click Commit changes and confirm the changes by clicking Commit scope changes.
Provide the 10Duke Support team with the object type ID. This ID is required for mapping the custom license grant object in 10Duke Scale.

You can find the ID in your browser’s address bar when viewing the custom object in the HubSpot settings. In the example URL below, the object type ID is the final segment: 2-61964602.

https://app.hubspot.com/object-type-settings/51424647/object/2-61964602

Setup in 10Duke Scale

Lifecycle stage configuration

With the optional lifecycle stage configuration, you can limit customer creation in 10Duke Scale to only be triggered for specific HubSpot lifecycle stages.

Provide the 10Duke Support team with the HubSpot Company lifecycle stage values that should trigger customer creation.

When the configuration is in place, creating a company in HubSpot with any other lifecycle stage value will not trigger the customer to be created in 10Duke Scale.

Only when you change the lifecycle stage in HubSpot to one of the configured values, customer creation is triggered in 10Duke Scale as described in company creation.

Deal stage configuration

With the optional deal stage configuration, you can limit the issuing of new licenses in 10Duke Scale to only be triggered for specific HubSpot deal stages.

Provide the 10Duke Support team with the HubSpot Deal stage values that should trigger the issuing of the licenses.

When the configuration is in place, creating a deal in HubSpot with any other deal stage value will not trigger the licenses to be issued in 10Duke Scale.

Only when you change the deal stage in HubSpot to one of the configured values, the issuing of the licenses is triggered in 10Duke Scale as described in license grants.

Configuration for selecting contact for B2B customer

With the optional configuration for selecting the contact for a B2B customer in 10Duke Scale, you can set the contact creation to only be triggered for a specific value in the Tenduke Type custom property in HubSpot when creating a new company.

Provide the 10Duke Support team with the HubSpot Tenduke Type value that should trigger the contact creation.

When the configuration is in place, creating a new company and linking a contact to it in HubSpot with any other Tenduke Type value will not trigger the customer to be created in 10Duke Scale.

Only when you set the value of the Tenduke Type custom property in HubSpot to the configured value and link the contact to the company, the customer and contact creation is triggered in 10Duke Scale as described in company creation.