# Trigger

> **Warning:** This connector was updated from version 5.0 to 6.0. Review the breaking changes below before updating your workflows.

## Overview

The HubSpot Trigger connector allows you to initiate workflows when specific events occur in HubSpot. Receive real-time notifications for CRM events, property changes, and custom actions to automate your business processes.

Version 6.0 introduces a more flexible subscription format with property-level filtering capabilities and enhanced event configuration.

### Available Operations

* **Webhook (event subscription)** - Subscribe to CRM events and property changes
* **Webhook (custom actions)** - Receive notifications from HubSpot workflows

## API Information

The Base URL used for this connector is **<https://api.hubapi.com>**.

More information can be found in HubSpot's [Webhooks API documentation](https://developers.hubspot.com/docs/api/webhooks). Webhooks must be served over HTTPS from a publicly accessible endpoint.

> **Info:** The HubSpot Trigger connector was upgraded at the end of February 2026 and uses HubSpot's API v3

## Breaking Changes in Version 6.0

### Version Summary

The HubSpot Trigger connector has been updated from version 4.0/5.0 to 6.0 with significant changes:

* **Authentication**: Token authentication removed; OAuth2 only
* **Subscription Format**: Array format has been adopted to provide more flexibility

### Authentication Changes

**Removed:** Token authentication (private apps)

**Why:** HubSpot deprecated private app tokens for webhook functionality. Private applications do not support webhooks.

**Required:** OAuth2 authentication only

**Migration:** All workflows using token-based authentication must be updated to use OAuth2 authentication. See the Authentication section below for setup instructions.

### Subscription Schema Changes

The subscription configuration format has fundamentally changed to provide more flexibility and control.

**Old format (v4.0/v5.0):**

```javascript
{
  subscription_types: {
    "contact.creation": true,
    "contact.propertyChange": true,
    "deal.deletion": false
  }
}
```

**New format (v6.0):**

```javascript
{
  subscription_types: [
    {
      standard_event: {
        object_type: "contact",
        event_type: "creation"
      }
    },
    {
      all_property_changes: {
        object_type: "contact"
      }
    }
  ]
}
```

**Benefits of the new format:**

The new subscription format enables more flexible subscription filtering, including property-level filtering where you can subscribe to specific property changes (e.g., only when "dealstage" changes).

### Migration Guide

Follow these steps to migrate your workflows from v4.0/v5.0 to v6.0:

**Step 1: Update Authentication**

* Remove any token-based authentications
* Add new OAuth2 authentication (see Authentication section)
* Update all workflows to use the new OAuth2 authentication

**Step 2: Convert Subscription Configurations**

Common conversion examples:

**Contact creation:**

* Old: `{ "contact.creation": true }`
* New: `[{ "standard_event": { "object_type": "contact", "event_type": "creation" } }]`

**Deal property changes (any property):**

* Old: `{ "deal.propertyChange": true }`
* New: `[{ "all_property_changes": { "object_type": "deal" } }]`

**Company deletion:**

* Old: `{ "company.deletion": true }`
* New: `[{ "standard_event": { "object_type": "company", "event_type": "deletion" } }]`

**Multiple subscriptions:**

* Old: `{ "contact.creation": true, "deal.propertyChange": true }`
* New: `[{ "standard_event": { "object_type": "contact", "event_type": "creation" } }, { "all_property_changes": { "object_type": "deal" } }]`

**Step 3: Test Webhook Delivery**

1. Enable your updated workflow
2. Trigger test events in HubSpot
3. Verify workflow execution with new format

***

> **Info:** For whitelabelling purposes, it is possible to use a Custom OAuth app with the HubSpot trigger.
> Please see the [Creating Custom OAuth Apps](https://tray.ai/documentation/connectors/service/hubspot/notes-for-custom-service-environment/#creating-custom-oauth-apps-cli-projects-framework) section for details on setting up custom OAuth apps using HubSpot's CLI and projects framework.

***

## Authentication

The HubSpot Trigger uses OAuth2 authentication exclusively. Token authentication (private apps) is not supported for webhooks.

### OAuth2 Setup in Tray Platform

1. Select the HubSpot Trigger in your workflow
2. Click the **Authenticate** tab in the properties panel
3. Click **Add new authentication**

> **Warning:** **OAuth2 Required**: You must use OAuth2 authentication. Private applications (token-based authentication) do not support webhooks per HubSpot's API limitations.

![hubspot-trigger](https://tray.ai/documentation/images/connectors/service/hubspot/ef54dbfa-41a64001_;askdjhf.png)
![hb-auht-trigger-o2](https://tray.ai/documentation/images/connectors/service/hubspot/4L5ScTusRvDrQnY59Ifj5y_hb-auht-trigger-o2.png)

For detailed authentication instructions, including scope selection and custom OAuth app setup, see the [HubSpot Authentication](https://tray.ai/documentation/connectors/service/hubspot/authentication) page.

### OAuth App Configuration for Webhooks

When creating or configuring your HubSpot OAuth app to work with webhooks, you need to configure webhook settings in your app:

1. **Create or access your HubSpot OAuth app** in your HubSpot developer account
2. **Configure webhook settings** including the `legacyCrmObjects` array
3. **Add the webhook URL** (see Webhook Configuration section below)

> **Info:** HubSpot OAuth apps should be created using HubSpot's Developer Platform (version 2025.2+) with the CLI-based projects framework. The legacy UI-based approach for creating OAuth apps has been deprecated. See [Creating Custom OAuth Apps](https://tray.ai/documentation/connectors/service/hubspot/notes-for-custom-service-environment/#creating-custom-oauth-apps-cli-projects-framework) for setup instructions using the CLI.

The `legacyCrmObjects` setting is an array containing classic subscription types (such as `contact.creation` and `deal.deletion`) that your app will support.

For complete instructions on configuring webhooks in your HubSpot OAuth app, refer to HubSpot's [webhook configuration guide](https://developers.hubspot.com/docs/apps/developer-platform/add-features/configure-webhooks).

> **Info:** Required scopes depend on which HubSpot objects you want to monitor. Refer to the [Scopes](https://tray.ai/documentation/connectors/service/hubspot/notes-on-using-hubspot/#scopes-cont) section for detailed scope requirements.

## Webhook Configuration

If you are using a **custom service environment** (embedded solutions, whitelabeling, or custom OAuth apps), the webhook URL format requires a mandatory query parameter.

### Custom Service Environment Webhook URLs

> **Warning:** **Required for Custom Environments**: The `app_key` query parameter is mandatory for all custom service environments. Without it, webhooks will not route correctly and your workflows will not trigger.

**URL Format:** `{base_url}?app_key={CLIENT_ID}`

Where `{CLIENT_ID}` is the **Client ID** (also called "App Key" in Tray UI) from your HubSpot OAuth app.

**Example URLs:**

Production (US):

```
https://webhooks.tray.io/production/webhooks/hubspot/1?app_key=abc123-def456-ghi789
```

Production (EU):

```
https://webhooks.eu1.tray.io/production/webhooks/hubspot/1?app_key=abc123-def456-ghi789
```

> **Info:** Select the URL for your region (US or EU) and replace `abc123-def456-ghi789` with your OAuth app's Client ID.

> **Warning:** **Tray Platform Requirement**: The `app_key` parameter is mandatory for all custom service environments. This is not optional - without it, webhook events will fail to route and your workflows will not trigger.

#### Finding Your Client ID

To find your OAuth app's Client ID:

1. Navigate to your HubSpot developer account
2. Open your OAuth app settings
3. Go to the **Auth** tab
4. Copy the **Client ID** value
5. This Client ID is your `app_key` value for the webhook URL

![HubSpot OAuth app Client ID location](https://tray.ai/documentation/images/connectors/service/hubspot/hubspot-oauth-client-id-location.png)

For detailed OAuth app setup instructions, see [Custom OAuth apps](https://tray.ai/documentation/connectors/service/hubspot/notes-for-custom-service-environment/#custom-oauth-apps).

### Configuration Guide

Because the webhook URL depends on the OAuth app's Client ID, webhook configuration requires a two-step deployment process:

> **Info:** You must deploy your OAuth app first to obtain the Client ID, then configure webhooks with that Client ID in a separate deployment. This applies whether you're creating a new app or adding webhooks to an existing app.

**Configuration Steps:**

1. **Create or access your HubSpot OAuth app** with basic configuration (name, logo, scopes)
2. **Save and deploy the app** to generate the Client ID
3. **Note the Client ID** from the Auth tab
4. **Construct your webhook URL:** `{base_url}?app_key={CLIENT_ID}`
5. **Return to your HubSpot app's webhook settings**
6. **Add the webhook URL** with the `app_key` parameter
7. **Configure `legacyCrmObjects` array** (see HubSpot's webhook guide)
8. **Save and deploy** the webhook configuration

**Why webhook configuration requires separate deployment:**

* The `app_key` query parameter (your Client ID) is only available after the app is initially deployed
* Tray's webhook routing system uses this parameter to route events correctly in custom service environments
* This is a Tray platform requirement for all custom service deployments

### Webhook Configuration in HubSpot

After constructing your webhook URL with the `?app_key={CLIENT_ID}` parameter, configure webhooks in your HubSpot project:

1. Create a `*-hsmeta.json` file in your project's `src/app/webhooks/` directory
2. Define webhook settings including the `targetUrl` with your `?app_key={CLIENT_ID}` parameter
3. Configure the `legacyCrmObjects` array with your subscription types
4. Deploy your app configuration

**Example webhook configuration file:**

```json
{
  "uid": "my-webhook-config",
  "type": "webhooks",
  "config": {
    "settings": {
      "targetUrl": "https://webhooks.tray.io/production/webhooks/hubspot/1?app_key=abc123-def456-ghi789",
      "maxConcurrentRequests": 10
    },
    "subscriptions": {
      "crmObjects": [],
      "legacyCrmObjects": [
        {
          "active": true,
          "subscriptionType": "contact.creation"
        },
        {
          "active": true,
          "subscriptionType": "contact.deletion"
        },
        {
          "active": true,
          "subscriptionType": "company.creation"
        },
        {
          "active": true,
          "subscriptionType": "company.deletion"
        },
        {
          "active": true,
          "propertyName": "email",
          "subscriptionType": "contact.propertyChange"
        },
        {
          "active": true,
          "propertyName": "dealstage",
          "subscriptionType": "deal.propertyChange"
        },
        {
          "active": true,
          "propertyName": "industry",
          "subscriptionType": "company.propertyChange"
        }
      ],
      "hubEvents": [
        {
          "subscriptionType": "contact.privacyDeletion",
          "active": true
        }
      ]
    }
  }
}
```

> **Info:** Replace `abc123-def456-ghi789` with your actual Client ID. Each subscription in `legacyCrmObjects` is an object with `active` (boolean) and `subscriptionType` properties. For property-specific subscriptions, include the `propertyName` field. The subscriptions shown are examples; configure your `legacyCrmObjects` and `hubEvents` arrays based on your specific integration needs. Leave `crmObjects` empty.

For complete webhook configuration file structure and instructions, refer to HubSpot's [webhook configuration guide](https://developers.hubspot.com/docs/apps/developer-platform/add-features/configure-webhooks).

***

## Webhook Payloads

Understanding the webhook payload structure is essential for processing events in your Tray workflows. The trigger outputs different payload formats depending on the webhook type.

### Event Subscription Webhooks

When HubSpot CRM events occur (contact creation, property changes, etc.), the trigger outputs the event data wrapped in a `body` object.

**Example Payload:**

```json
{
  "body": {
    "eventId": 2796351857,
    "subscriptionId": 251491,
    "portalId": 7985479,
    "appId": 33232,
    "occurredAt": 1593698753647,
    "subscriptionType": "contact.propertyChange",
    "attemptNumber": 0,
    "objectId": 901,
    "changeSource": "CONTACTS",
    "propertyName": "email",
    "propertyValue": "test@tester2001.com"
  }
}
```

**Key Fields (accessed via `body.fieldName`):**

* `body.eventId` - Unique identifier for this event
* `body.subscriptionId` - ID of the webhook subscription in HubSpot
* `body.portalId` - HubSpot account (portal) ID
* `body.appId` - HubSpot app ID
* `body.occurredAt` - Timestamp in milliseconds when the event occurred
* `body.subscriptionType` - The type of event (format: `{objectType}.{eventType}`)
* `body.objectId` - The ID of the object that changed (contact ID, deal ID, etc.)
* `body.changeSource` - Source of the change (e.g., "CRM", "CONTACTS")
* `body.propertyName` - For property changes, the name of the property that changed
* `body.propertyValue` - The new value of the property
* `body.attemptNumber` - Retry attempt number (0 for first attempt)

**Common Subscription Types:**

* `contact.creation` - When a new contact is created
* `contact.propertyChange` - When any property on a contact changes
* `deal.deletion` - When a deal is deleted
* `company.propertyChange` - When any property on a company changes
* `ticket.associationChange` - When associations with a ticket change

### Custom Action Webhooks

When HubSpot workflows invoke custom actions, the webhook payload includes workflow context and the object being processed.

**Example Payload:**

```json
{
  "callbackId": "ap-6496270-271746737576-8-0",
  "origin": {
    "portalId": 6496270,
    "actionDefinitionId": 20564589,
    "actionDefinitionVersion": 1
  },
  "context": {
    "source": "WORKFLOWS",
    "workflowId": 143220641
  },
  "object": {
    "objectId": 3101,
    "objectType": "CONTACT"
  },
  "inputFields": {}
}
```

**Key Fields:**

* `callbackId` - Unique identifier for this custom action invocation
* `origin.portalId` - HubSpot account ID
* `origin.actionDefinitionId` - ID of the custom action definition
* `context.workflowId` - ID of the HubSpot workflow that triggered this action
* `object.objectId` - The ID of the CRM object being processed
* `object.objectType` - The type of object (CONTACT, COMPANY, DEAL, TICKET, etc.)
* `inputFields` - Custom input fields configured in the action definition

> **Info:** For complete webhook payload specifications and request validation details, refer to HubSpot's [Webhooks API documentation](https://developers.hubspot.com/docs/api/webhooks).

***

## Available Operations

### Webhook (event subscription)

This operation triggers workflows when specified HubSpot events occur. Configure subscriptions using the new array format with three available variants.

> **Info:** Event filtering occurs within the Tray workflow after receiving webhooks from HubSpot, not at the HubSpot webhook registration level.

### Subscription Variants

Configure one or more subscription types to specify which events trigger your workflow. The example below shows all three variants configured together:

![HubSpot Trigger subscription configuration](https://tray.ai/documentation/images/connectors/service/hubspot/hubspot-trigger-subscription-variants-v6.png)

#### Variant 1: Standard Event

Subscribe to standard CRM events such as object creation, deletion, restoration, and merges.

**Configuration:**

* **Object Type**: Select from dropdown (dynamically loaded from HubSpot: contacts, companies, deals, tickets, products, line\_items, etc.)
* **Event Type**: Choose from available event types

**Available Event Types:**

* `creation` - Object created
* `deletion` - Object deleted
* `privacyDeletion` - Privacy-related deletion
* `associationChange` - Association between objects modified
* `restore` - Previously deleted object restored
* `merge` - Objects merged together

**Example Configuration:**

```json
{
  "subscription_types": [
    {
      "standard_event": {
        "object_type": "contact",
        "event_type": "creation"
      }
    }
  ]
}
```

**Use Cases:**

* Trigger workflow when new contact is created in HubSpot
* React to deal deletions and sync with external systems
* Monitor association changes between contacts and companies
* Track when records are restored after deletion

#### Variant 2: Property Change (All)

Subscribe to any property change on a specific object type. The workflow triggers whenever any property on the object is modified.

**Configuration:**

* **Object Type**: Select from dropdown

**Example Configuration:**

```json
{
  "subscription_types": [
    {
      "all_property_changes": {
        "object_type": "deal"
      }
    }
  ]
}
```

**Use Cases:**

* Audit all changes to deal records
* Sync any contact updates to external CRM
* Monitor all modifications to company records
* Track any changes for compliance purposes

#### Variant 3: Property Change (Specific)

Subscribe to specific property changes only. This is the most efficient option for targeted workflows as it filters to a single property.

**Configuration:**

* **Object Type**: Select from dropdown
* **Property Name**: Enter the exact internal property name (e.g., "email", "dealstage", "industry")

**Example Configuration:**

```json
{
  "subscription_types": [
    {
      "specific_property_change": {
        "object_type": "company",
        "property_name": "industry"
      }
    }
  ]
}
```

**Use Cases:**

* Trigger only when deal stage changes
* React specifically to email address updates
* Monitor changes to custom property fields
* Track status field modifications

### Combining Multiple Subscriptions

You can combine multiple subscription variants in a single array to monitor different events with one trigger.

**Example - Multiple Subscriptions:**

```json
{
  "subscription_types": [
    {
      "standard_event": {
        "object_type": "contact",
        "event_type": "creation"
      }
    },
    {
      "specific_property_change": {
        "object_type": "deal",
        "property_name": "dealstage"
      }
    },
    {
      "all_property_changes": {
        "object_type": "company"
      }
    }
  ]
}
```

This configuration triggers the workflow when:

* A new contact is created, OR
* The deal stage property changes on any deal, OR
* Any property changes on any company

### Finding Property Names

To find the exact internal property name for specific property change subscriptions:

1. Navigate to HubSpot Settings → Properties
2. Select the object type (Contacts, Deals, Companies, etc.)
3. Find the property and use the **internal property name** (not the display label)
4. Common examples:
   * Email address: `email`
   * Deal stage: `dealstage`
   * Company industry: `industry`
   * Contact lifecycle stage: `lifecyclestage`

For a complete property reference, see HubSpot's [Properties API documentation](https://developers.hubspot.com/docs/api/crm/properties).

### Webhook (custom actions)

The property panel for this event is left deliberately blank as the attributes for it are created / connected via the HubSpot UI (not the Tray.io builder).
See steps below for a use case basic example.
![hbs-custom-actions-main](https://tray.ai/documentation/images/connectors/service/hubspot/fJ5qWdWONocVPW3YFECE4_hbs-custom-actions-main.png)

### 1 - Add your Trigger

Add the HubSpot Trigger to your workflow and configure authentication.
![hb-trigger-builder](https://tray.ai/documentation/images/connectors/service/hubspot/2rhJEWun0fraSaUNifLgpU_hb-trigger-builder.png)

### 2 - Create a user form

Create a simple test form via the main HubSpot UI and use the public URL to test your submissions.
**Make sure to enable your Tray.io workflow BEFORE submitting your form** - otherwise the trigger will not pick up the action.
![hb-trigger-form-1](https://tray.ai/documentation/images/connectors/service/hubspot/79fbxrvtLxXLJQYCic8JQf_hb-trigger-form-1.png)
![form-hb-1](https://tray.ai/documentation/images/connectors/service/hubspot/2K2C4z3lMfPqkRK1Cst9Sn_form-hb-1.png)
![form-hs-2](https://tray.ai/documentation/images/connectors/service/hubspot/70gjAPVxp2ty3H6XrEK9BO_form-hs-2.png)

### 3 - Create a workflow in HubSpot

Build a simple two step HubSpot workflow. Attach the recently created form to your trigger.
Make sure to select **Send to Tray.io** from the action options list.
![hb-form-wf-1](https://tray.ai/documentation/images/connectors/service/hubspot/NYnJmYdMCDuarv6MwuB2N_hb-form-wf-1.png)
![hb-wf-trigger-setup-1](https://tray.ai/documentation/images/connectors/service/hubspot/1gScADKjbJvyz9ZyNYyMIq_hb-wf-trigger-setup-1.png)
![hb-wf-trigger-setup-2](https://tray.ai/documentation/images/connectors/service/hubspot/5BOWSaVITDRKStaKP7Zckn_hb-wf-trigger-setup-2.png)
![hb-wf-trigger-setup-3](https://tray.ai/documentation/images/connectors/service/hubspot/2FYOxMHb9puIr77JIMr3DZ_hb-wf-trigger-setup-3.png)

### 4 - Submit your HubSpot form & test your workflow

Make sure your **Tray.io workflow is enabled** before sumbitting your HubSpot form.
Your **HubSpot workflow does NOT need to be published** in order to register a call.
![hb-form-sumbit-3](https://tray.ai/documentation/images/connectors/service/hubspot/4HEZ9ubVU54QyECYTfnQHb_hb-form-sumbit-3.png)
![hb-form-trigger-complete](https://tray.ai/documentation/images/connectors/service/hubspot/6O1kkACO8jl4DaD0gz39kP_hb-form-trigger-complete.png)

***

## Troubleshooting

### Webhooks Not Firing

**Check authentication:**

* Verify OAuth2 authentication is active (not token-based)
* Ensure OAuth app has webhook permissions configured
* Confirm webhook URL is correctly configured in HubSpot app settings
* Verify `legacyCrmObjects` array is correctly configured in your HubSpot OAuth app webhook settings (not other webhook configuration properties)

**Check subscription configuration:**

* Verify subscription array format is correct (v6.0 format, not v4.0/v5.0)
* Ensure object types and event types are valid
* Test with a simple subscription first (single standard event)

**Check workflow state:**

* Workflow must be enabled in Tray platform
* Trigger must be configured and authenticated before testing

### Authentication Errors

**"Private apps don't support webhooks" error:**

* This indicates token authentication is being used
* **Solution**: Switch to OAuth2 authentication
* Private apps (token-based) cannot receive webhooks per HubSpot's API limitations

### Property Filtering Not Working

**Receiving events for all properties instead of specific property:**

* Verify property name is the exact **internal property name** (not the display label)
* Check HubSpot Settings → Properties to confirm the internal name
* Remember: Property names are case-sensitive
* Refer to HubSpot's [Properties API documentation](https://developers.hubspot.com/docs/api/crm/properties) for property names

**Note:** Filtering happens within the Tray workflow after HubSpot sends the webhook. The trigger receives all configured subscriptions and filters based on your array configuration.

### Webhook Delivery Issues

**Payloads not reaching workflow:**

* Verify webhook URL is correctly configured in your HubSpot OAuth app
* Ensure the URL matches your region (US vs EU) and environment (development vs production)
* Check that your HubSpot app has the webhook feature enabled
* Test webhook delivery using HubSpot's webhook testing tools in the developer portal
* Monitor HubSpot's webhook delivery logs for failed attempts or errors

**Subscription not receiving expected events:**

* Verify the object type supports the event type you selected
* Check that test events in HubSpot actually match your subscription criteria
* Ensure your workflow is enabled before triggering test events
* Review the HubSpot webhook delivery logs to see what events are being sent