Connect to HubSpot

This article provides instructions on the steps required from you (the vendor) to integrate 10Duke Enterprise 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 Enterprise, which then triggers the corresponding actions.

In 10Duke Enterprise, licenses are provisioned either as fixed-term licenses (with a defined start and end date) or perpetual licenses (with no end date).

To support HubSpot subscriptions, 10Duke Enterprise provisions subscriptions as perpetual licenses with no initial end date. These licenses remain active for as long as the subscription remains valid in HubSpot.

If a subscription lifecycle event occurs in HubSpot—such as cancellation, expiration, or payment failure—10Duke Integration Service automatically updates the corresponding license in 10Duke Enterprise by applying an end date, effectively terminating access.

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 the 10Duke Integration Support team 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 Enterprise, which are handled by the 10Duke Integration Support team.

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, contacts, 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 Enterprise. 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.

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 the 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 organization is created in 10Duke Enterprise until the related Contact data is available for the Company. Organization creation in 10Duke Enterprise 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 organization’s first administrator user is used, the Company results in a visible organization in 10Duke Enterprise 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 organization’s first administrator user are used, the Company does not result in a visible organization in 10Duke Enterprise until the value that triggers the admin user 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 Enterprise 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 package 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 Enterprise:

For a B2B customer, this creates:
- A new organization in 10Duke Enterprise.
  
  Note: The HubSpot company ID is automatically mapped to the corresponding organization in 10Duke Enterprise. This enables retrieval of organization details using the HubSpot company ID. This functionality is available from the 10Duke Enterprise release 6 onwards.
- A user account for the organization’s first administrator, with access to the 10Duke OrgAdmin tool (if you’re providing it for your B2B customers).
- A default entitlement to hold the organization’s licenses.
- An “employees” user group, where the first administrator user is added and which is granted access to the default entitlement.
An email is sent to the created user, who must activate their account by setting a password or registering a passkey.

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

Optionally, customer creation in 10Duke Enterprise 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 Enterprise until the customer relationship has been established.

You can also optionally configure a specific contact to be selected as the organization’s first administrator user for a B2B customer in 10Duke Enterprise. 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 Enterprise.

To create a company for a B2B customer in HubSpot:

Provide a company name. This is set as the name of the organization in 10Duke Enterprise.
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 Enterprise.

Create a contact by providing at least the following details:
- First name
- Last name
- Email address (must be unique across all 10Duke Enterprise users)
- Phone number (optional)
- Tenduke Type
  
  If the configuration for selecting a specific contact as the organization’s first administrator user in 10Duke Enterprise is in use, select the Tenduke Type value that will be used to trigger the admin user 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 organization is not created in 10Duke Enterprise. The company is created only when the contact is linked to the company and the configured Tenduke Type value is present.
These are set as the name and email address of the B2B customer organization’s first administrator user in 10Duke Enterprise. This user is granted access to the OrgAdmin tool, if enabled.
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 Enterprise.

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 Enterprise:

If the optional lifecycle stage configuration is in use, the update can trigger the first-time creation of the customer in 10Duke Enterprise (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 Enterprise, 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 Enterprise user account is taken from that contact’s current email address in HubSpot.

If a company has multiple contacts, ensure that the intended administrator contact is configured correctly before triggering customer creation.

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 Enterprise. 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 following actions in 10Duke Enterprise:

New licenses are granted to the customer (a B2B organization).

The event specifies one or more SKUs in HubSpot products, which map to 10Duke Enterprise product packages used for granting the licenses.
For a B2B customer, the licenses are always created in the organization’s default entitlement.

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’re creating the line item object within the deal. Otherwise, select the correct deal.
- SKU: This must match the product package in 10Duke Enterprise that is used for granting the licenses.
  
  If the Product Code custom property is in use, it defines the product package in 10Duke Enterprise instead of SKU.
- Term: The length of the license validity. It defines the type of license created in 10Duke Enterprise:
  - 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 package, 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 Enterprise.

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 Enterprise.
- 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 package in 10Duke Enterprise that is used for granting the licenses.
- Product Package Name: When Product ID is not provided, the Product Package Name is used instead. Define the name of the product package in 10Duke Enterprise that is used for granting the licenses.
- Quantity: The number of product packages used to grant licenses, used for calculating the final license credit. This number is effectively a multiplier for the credit amount defined for the licensed item in the product package.
- Company ID: The organization in 10Duke Enterprise 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

Note: When the licenses are granted through the Graph API new licenses are granted to the customer (a B2B organization) that are valid until the end of the new subscription period, and the old licenses are deleted. If there were seat reservations for the old licenses, those are also deleted.

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 package, 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 Enterprise. 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 package.

Delete licenses

If you delete a line item from a deal (a one-time deal or a subscription) in HubSpot, HubSpot sends a delete event that triggers an update to the validity of the licenses associated with the line item in 10Duke Enterprise. The valid until date is set to the current instant (now), making the licenses invalid with immediate effect.

In the same way, if you delete the whole deal in HubSpot, HubSpot sends a delete event that triggers an update to the validity of all the licenses associated with the deal’s line item objects in 10Duke Enterprise. The valid until date is set to the current instant (now) making all the licenses invalid with immediate effect.

Note: If you delete a line item from a deal (a one-time deal or a subscription) or the whole deal in HubSpot, and the licenses are granted through the Graph API, the delete event triggers the deletion of the licenses associated with the deal or deal’s line items in 10Duke Enterprise.

If you delete a license grant object in HubSpot, HubSpot sends a delete event that triggers the deletion of associated licenses in 10Duke Enterprise.

Limitations

Updates to customer details in 10Duke Enterprise are not supported.
For B2B customers’ subscriptions, note that if you move granted licenses to other entitlements, updating a subscription’s licenses may affect how the organization’s users and devices can access those licenses in 10Duke Enterprise. See more information on authorizing access to licenses.

Note: When the licenses are granted through the Graph API the integration only supports granting seat-based 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 the 10Duke Enterprise.

After all the setup steps have been completed, the 10Duke Integration Support team can enable the integration in 10Duke Enterprise.

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

If the configuration for selecting a specific contact as the organization’s first administrator user in 10Duke Enterprise 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 package in 10Duke Enterprise, 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 the 10Duke Integration Support team 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: closedateand dealname
    
    If the deal stage configuration is in use in 10Duke Enterprise, 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 the administrator user is in use in 10Duke Enterprise, 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 Enterprise, 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 Enterprise 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 package name is used for granting licenses:
    - Define the name of the property: Product Package Name.
    - Set the property type to Single-line text.
    - Click the pen icon below the name, edit the property’s API name to productpackagename 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 scope:
  - 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, productpackagename, quantity, validfrom, and validuntil.
  - Click Subscribe.
- Click Commit changes and confirm the changes by clicking Commit scope changes.
Provide the 10Duke Integration Support team with the object type ID. This ID is required for mapping the custom license grant object in 10Duke Enterprise.

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 Enterprise

After all the setup steps in HubSpot have been completed, the 10Duke Integration Support team will help complete the setup in 10Duke Enterprise and activate the connection between HubSpot and 10Duke Enterprise.

The setup includes enabling the Integration Service component for your deployment and defining the connection between the component and 10Duke Enterprise as an OAuth client application, which you will see in SysAdmin, and setting up the lifecycle stage, deal stage, or administrator user selection configuration if needed (see below).

Lifecycle stage configuration

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

Provide the 10Duke Integration 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 Enterprise.

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

Deal stage configuration

With the optional deal stage configuration, you can limit the issuing of new licenses in 10Duke Enterprise 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 Enterprise.

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

Configuration for selecting administrator user

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

Provide the 10Duke Integration Support team with the HubSpot Tenduke Type value that should trigger the admin user 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 organization creation in 10Duke Enterprise.

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 organization and admin user creation is triggered in 10Duke Enterprise as described in company creation.