> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cometly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HubSpot integration

> Set up the HubSpot Cometly integration to send new contacts, property changes and deals as events tied to the ads that produced them.

The HubSpot Cometly integration sends contact and deal activity from your HubSpot CRM to Cometly. When a contact is created, a property such as the lifecycle stage changes, or a deal is created, moved or won, Cometly receives it as an event: a conversion, such as a lead or a closed deal, that Cometly ties back to the ad or marketing channel the contact came from.

This matters because the outcome of a lead usually lives in your CRM, not on your website. With HubSpot connected, you can see which ads and channels produce qualified leads, deals and revenue, not only form fills, and decide where to spend based on that.

> [!NOTE]
>
> We recommend that a **Super Admin** installs the Cometly app in HubSpot, but it is not required.
>
> You can connect HubSpot to Cometly as long as your user has the correct CRM object permissions and App Marketplace access. These permissions allow Cometly to receive contact and deal data through webhooks.
>
> [Learn how to check your HubSpot user permissions](https://docs.cometly.com/support/troubleshooting/integrations/hubspot-user-permissions.md)

## Available triggers

Each Cometly event you create for HubSpot uses one trigger. The trigger decides when HubSpot sends the event to Cometly.

| Trigger | Fires when | You also select |
| - | - | - |
| **Contact Created** | Any new contact is created in HubSpot. | Nothing else |
| **Contact Property Change** | The chosen property is updated on any contact. | A property |
| **Deal Created** | A new deal is created. | A pipeline and a pipeline stage |
| **Deal Property Change** | The chosen deal property is updated. | A property, a pipeline and a pipeline stage |
| **Deal Stage Updated** | A deal's stage is updated. | A pipeline and a pipeline stage |
| **Deal Closed Won** | A deal moves to Closed Won. | A pipeline and a pipeline stage |

A typical use of **Contact Property Change** is the lifecycle stage: when a contact moves from *Lead* to *MQL*, an MQL event is sent to Cometly.

For the **Deal Created** trigger to work, always associate a contact when you create a deal, and create the deal in the stage you selected in Cometly. See [Requirements for the Deal Created trigger](#requirements-for-the-deal-created-trigger).

### Using HubSpot forms?

If you use HubSpot marketing forms on your website, set them up for tracking before you send events: see [HubSpot forms (new editor)](https://docs.cometly.com/integrations/forms/hubspot.md) or [HubSpot legacy forms](https://docs.cometly.com/integrations/forms/hubspot-legacy-forms.md).

### Prefer HubSpot workflows?

You can also send event data to Cometly from your HubSpot workflows with a webhook. This is a good option if you want full control over which events are sent and when. Your HubSpot plan must include webhooks to use this method. See [Send HubSpot events with webhooks](https://docs.cometly.com/integrations/guides/hubspot-webhooks.md).

## Step 1: Install the Cometly pixel

Install the Cometly pixel (the tracking script that records the visitors who reach your site) in the `<head>` of every page of your website, including the thank-you page.

See [Install and verify the Cometly pixel](https://docs.cometly.com/getting-started/install-pixel.md).

## Step 2: Create the event

In Cometly, open [**Events Manager**](https://app.cometly.com/space/events-manager) and click **Create Event**.

![Events tab of the Cometly Events Manager with three events in the table and an arrow pointing at the Create Event button](https://mintcdn.com/cometly/gJhojf-axy7BVk83/images/integrations/platforms/hubspot/01.webp?fit=max\&auto=format\&n=gJhojf-axy7BVk83\&q=85\&s=35bed38d479712012fc3770d5c641037)

In the **Create Event** dialog:

1. Under **App / Integration**, select **HubSpot**.
2. Under **Events**, choose a standard event, or click **Create New Event** to make a custom one.
3. Click **Create**.

![Create Event dialog with numbered callouts: 1 on HubSpot under App / Integration, 2 on the Lead event under Events and 3 on the Create button](https://mintcdn.com/cometly/gJhojf-axy7BVk83/images/integrations/platforms/hubspot/02.webp?fit=max\&auto=format\&n=gJhojf-axy7BVk83\&q=85\&s=1a447a94452a3176d00213bf2ef43bd7)

## Step 3: Configure the event and the HubSpot connection

Click **Configure** next to the new event to start setting up the HubSpot integration.

![Events Manager table filtered to one Lead event for HubSpot in Draft status, with an arrow pointing at its Configure button](https://mintcdn.com/cometly/gJhojf-axy7BVk83/images/integrations/platforms/hubspot/03.webp?fit=max\&auto=format\&n=gJhojf-axy7BVk83\&q=85\&s=3acd400532e71cd47ab5fc1fc8eba866)

Choose the HubSpot account and the trigger that will send this event to Cometly.

1. **App**: pre-selected as **HubSpot**.

2. **Account**: click **Select an account** and pick the HubSpot account you want to use. If this is your first time connecting HubSpot to Cometly, click **Connect new account** to add your HubSpot connection.

3. **Trigger**: click **Choose trigger** and pick one of the [available triggers](#available-triggers). Depending on the trigger, more fields appear:

   * **Property Name** (Contact Property Change and Deal Property Change). Choose the specific property to watch, such as *Lifecycle Stage*, *Lead Status* or any custom property you use. Whenever that property is updated, the trigger fires and sends the event to Cometly. For example:

     * If you select **Lifecycle Stage** and a contact moves from *Lead* to *MQL*, an MQL event can be sent to Cometly.
     * If you select **Lead Status** and it changes from *New* to *Qualified*, a Qualified Lead event can be sent.

     Choose a property that matches the event you want to track in Cometly. The most common selection is **Lifecycle Stage**.

   * **Pipeline** and **Pipeline stage** (all four deal triggers).

4. Click **Continue**. The button stays disabled, and tells you what is missing, until every required field is selected.

> [!WARNING]
>
> Once selected, the **Account** and **Trigger** cannot be modified. To use a different account, trigger or property, you have to create a new event. Double-check your selections before you continue.

### Retrieve data for your trigger

To test the integration, make the trigger fire in HubSpot, then click **Check for Data** in Cometly. Follow the steps for your trigger type:

> [accordion] Contact Created trigger
>
> This trigger fires when any new contact is created in your HubSpot account.
>
> 1. **Create a test contact in HubSpot.** Go to your HubSpot account and manually add a new contact.
> 2. **Click Check for Data.** This fetches the most recent contact records from HubSpot. If no data appears, double-check that your test contact was created, then try again.
> 3. **Select your event record.** Choose the record that matches the test contact you just created.
> 4. **Click Continue With Selected Record.**

> [accordion] Contact Property Change trigger
>
> This trigger fires when a specific property (such as Lifecycle Stage or Lead Status) is updated on any contact.
>
> 1. **Update the property on an existing contact.** In HubSpot, open any contact and change the property you are tracking (for example, change *Lifecycle Stage* from *Lead* to *MQL*).
> 2. **Click Check for Data.** This pulls the latest contact property change events from HubSpot. Make sure you changed the **exact** property selected in your trigger. If no data appears, update the property again and retry.
> 3. **Select your event record.** Choose the record that shows the recent property change.
> 4. **Click Continue With Selected Record.**

> [accordion] Deal Created trigger
>
> This trigger fires when a new deal is created in your HubSpot account.
>
> 1. **Create a test deal in HubSpot.** Select the pipeline and stage defined in your trigger and manually create a new deal. Associate a contact with it.
> 2. **Click Check for Data.** This fetches the most recent deal records from HubSpot. Make sure the test deal matches the selected pipeline and stage.
> 3. **Select your event record.** Choose the record that matches the test deal you just created.
> 4. **Click Continue With Selected Record.**

> [accordion] Deal Property Change trigger
>
> This trigger fires when a specific property is updated on a deal.
>
> 1. **Update the selected deal property.** Open any deal in the selected pipeline and stage in HubSpot and change the exact property you selected in the trigger (for example the deal type or a custom property).
> 2. **Click Check for Data.** This fetches the most recent property change events from HubSpot. Make sure you changed the **correct property** and that the deal is in the selected pipeline and stage.
> 3. **Select your event record.** Pick the record that reflects the recent property update.
> 4. **Click Continue With Selected Record.**

> [accordion] Deal Stage Updated trigger
>
> This trigger fires when the stage of a deal is updated in the selected pipeline.
>
> 1. **Update the stage of a deal.** Open a deal in the pipeline you selected and move it to a different stage.
> 2. **Click Check for Data.** This pulls the most recent deal stage update events. Make sure the deal is in the correct pipeline and the stage was actually updated.
> 3. **Select your event record.** Choose the record that shows the stage update.
> 4. **Click Continue With Selected Record.**

> [accordion] Deal Closed Won trigger
>
> This trigger fires when a deal reaches the **Closed Won** stage in the selected pipeline.
>
> 1. **Move a deal to Closed Won.** In HubSpot, open any deal in the selected pipeline and move it to the **Closed Won** stage.
> 2. **Click Check for Data.** This retrieves the latest deals that were marked as Closed Won. If no data appears, double-check that the stage was set to Closed Won.
> 3. **Select your event record.** Pick the record that shows the deal you just closed.
> 4. **Click Continue With Selected Record.**

> [!NOTE]
>
> Don't see data yet? This can happen if no events have been sent yet. Click **Save & Return When Data is Ready** and come back later to map your data once events have been sent.

### How deal-to-contact matching works

To keep deal counts in Cometly one-to-one with HubSpot, **only one contact** is associated with a deal in Cometly.

If several contacts are associated with a HubSpot deal, Cometly chooses the contact like this:

1. If one or more contacts have a `first_conversion_date`, Cometly uses the contact with the earliest one.
2. If none of the contacts has a `first_conversion_date`, Cometly uses the contact with the earliest `createdate`.

This keeps reporting consistent and avoids inflating deal numbers when several contacts are linked to a single HubSpot deal.

### Requirements for the Deal Created trigger

For the **Deal Created** trigger to work, your team must create deals in HubSpot in a specific way. Use the instructions below to update your HubSpot settings so deals are always created correctly and data is sent to Cometly every time.

> [accordion] Require a contact to be associated when creating a deal
>
> Deals must have at least one contact associated. You can configure the deal creation form in HubSpot to *require* an associated contact, so this step is never missed.
>
> [Require Contact Association When Creating a Deal](https://www.loom.com/embed/344a35d069d54253926054889ae603ca)
>
> #### Instructions from the video
>
> 1. Click the **Settings** (gear) icon in your HubSpot account.
> 2. Under **Data Management** > **Objects**, click **Deals**.
> 3. Click **Customize the 'Create Deal' form**.
>
> ![HubSpot Deals settings with the Settings icon, Deals and Customize the Create Deal form numbered](https://mintcdn.com/cometly/gJhojf-axy7BVk83/images/integrations/platforms/hubspot/07.webp?fit=max\&auto=format\&n=gJhojf-axy7BVk83\&q=85\&s=231606e5d653ac04ee6b4f7251c2b1c0)
>
> 4. On the Create Deal form, go to the **Associations** section.
> 5. In the **Contacts** association box, hover over **Associate record** and click the **asterisk (\*)** to make the field required. Then click **Save and close**.
>
> ![HubSpot Edit Deal form with the Make required asterisk on the Contacts association and Save and close highlighted](https://mintcdn.com/cometly/gJhojf-axy7BVk83/images/integrations/platforms/hubspot/08.webp?fit=max\&auto=format\&n=gJhojf-axy7BVk83\&q=85\&s=359f8de6469cc4d65ba2d6c3b170e59b)

> [accordion] Require a specific pipeline stage when creating deals
>
> Deals must be created directly in the pipeline stage you selected when you set up the **Deal Created** trigger. You can limit deal creation in HubSpot to that stage.
>
> [How to require a specific Pipeline Stage when creating deals](https://www.loom.com/embed/70c0a02a88b04fd28983921aabadd373)
>
> #### Instructions from the video
>
> 1. Click the **Settings** (gear) icon in your HubSpot account.
>
> 2. Under **Data Management** > **Objects**, click **Deals**.
>
> 3. Click **Pipelines** and select the relevant pipeline.
>
> 4. Click **Pipeline Rules**.
>
>    ![HubSpot Deals Pipelines tab with an arrow pointing at Pipeline Rules](https://mintcdn.com/cometly/gJhojf-axy7BVk83/images/integrations/platforms/hubspot/09.webp?fit=max\&auto=format\&n=gJhojf-axy7BVk83\&q=85\&s=0f84cd1b086971b0d8d503c816693c99)
>
> 5. Turn on **Limit deal creation to specific stages**.
>
>    ![HubSpot Pipeline Rules with the Limit deal creation to specific stages toggle highlighted](https://mintcdn.com/cometly/gJhojf-axy7BVk83/images/integrations/platforms/hubspot/10.webp?fit=max\&auto=format\&n=gJhojf-axy7BVk83\&q=85\&s=7caa0e3e6922be8e5e0d9d728df02420)
>
> 6. Select the stage you selected in Cometly as the pipeline stage, then click **Save**.
>
>    ![HubSpot Limit deal creation to specific stages panel with a stage selected and Save highlighted](https://mintcdn.com/cometly/gJhojf-axy7BVk83/images/integrations/platforms/hubspot/11.webp?fit=max\&auto=format\&n=gJhojf-axy7BVk83\&q=85\&s=e1b43e39d5a6ec5d79590a86a16f094f)

## Step 4: Configure mapping

Map the HubSpot data fields to Cometly fields, so the event data you send (email addresses, event times and any other data) lines up with Cometly's reporting.

**Email** and **Event Time** are required.

1. **Email**: choose the email address field from your selected record (the sample value looks like `email@example.com`).
2. **Event Time**: choose the dynamic option **The time we receive the event**.

Click **Add Field** to map more fields, such as First Name, Last Name, Phone or Amount.

When you have mapped your data, click **Save & Continue**.

## Step 5: Configure filters and activate the event

Filters control **when** an event in HubSpot actually records an event in Cometly. This step is optional, but **highly recommended** when you track changes to a contact property (such as Lifecycle Stage) and only want to send the event under certain conditions.

Common uses for filters with HubSpot:

* Only send the event to Cometly when the lifecycle stage is MQL.
* Only send the event when a custom property (such as lead score or status) contains a specific value.
* Skip contacts that do not meet your qualification criteria.

> [!TIP]
>
> If you use the **Contact Property Change** trigger, a filter is the best way to make sure you only send events to Cometly when the property changes to the **specific value** you care about (such as "Customer" or "Opportunity").

To add a filter:

1. Click **Add Another Filter**. (For a new event, Cometly has already added one filter that requires the email field to be not empty.)
2. Select the field you want to filter by (for example the lifecycle stage, lead score or contact owner).
3. Choose a condition (for example **(text) is**, **(text) contains** or **(text) starts with**).
4. Enter the value you want to match (for example `MQL` or `SQL`).

Cometly tests your filters against the record you selected:

* If the record **matches**, you see **Your Webhook would have successfully continued**, with **PASS** next to each filter.
* If the record **does not match**, you see **Your Webhook would NOT have continued**, with **FAIL** next to the filter that stopped it.

When your filters are right, click **Activate** to switch the event on. (When you edit an event that is already active, the button reads **Save**.)

## Check it worked

In **Events Manager**, the event's row now shows the status **Active**. Make the trigger fire once more in HubSpot, then open the **Events Log** tab: the new event is listed there, and the row's **Total Events** count goes up.

## Frequently asked questions

### Why is my HubSpot deal not showing up in Cometly?

Cometly only records a deal event when the deal has at least one associated contact, because it needs a contact to attribute the deal to. The deal must also match the pipeline and pipeline stage you selected for the event. If no HubSpot events arrive at all, check the [HubSpot user permissions](https://docs.cometly.com/support/troubleshooting/integrations/hubspot-user-permissions.md) of the person who connected the account.

### Does the HubSpot integration import my existing contacts and deals?

No. The triggers fire when something happens in HubSpot, so Cometly receives events from the moment your event is active. A contact or deal that already existed is sent only if it later fires the trigger, for example when its tracked property changes.

### Can I connect more than one HubSpot account to Cometly?

Yes. When you configure an event, open the **Account** list and click **Connect new account** to add another HubSpot account. Each event uses the one account you select for it.

## Next steps

* [Check incoming events in the Events Log](https://docs.cometly.com/support/troubleshooting/general/event-log.md)
* [Learn how events work in Cometly](https://docs.cometly.com/guides/events/how-events-work.md)
* [Send your HubSpot conversions back to your ad platforms with the Conversion API](https://docs.cometly.com/guides/conversion-api/overview.md)
* [Fix HubSpot user permissions when events do not arrive](https://docs.cometly.com/support/troubleshooting/integrations/hubspot-user-permissions.md)
* [Send HubSpot events from workflows with webhooks](https://docs.cometly.com/integrations/guides/hubspot-webhooks.md)

Still have questions or need a hand? We're happy to help. Reach our team at [support@cometly.com](mailto:support@cometly.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.