HubSpot Destination Config Reference Beta

HubSpot is a CRM and marketing destination. RudderStack creates and updates contacts from identify calls and records track events, from its servers or — for web sources — through HubSpot’s own script in device mode.

In a HubSpot destination spec:

• type: hs
• definition_version: 1

Sample configuration

version: rudder/v1
kind: destination
metadata:
  name: hubspot-prod
spec:
  id: hubspot-prod
  display_name: HubSpot Production
  type: hs
  definition_version: 1
  enabled: true
  config:
    api_version: newApi
    access_token: "{{ .HUBSPOT_ACCESS_TOKEN }}"
    hub_id: "{{ .HUBSPOT_HUB_ID }}"
    lookup_field: email
    do_association: false

    hubspot_events:
      - rs_event_name: Order Completed
        hubspot_event_name: pe12345_order_completed
        event_properties:
          - from: revenue
            to: order_value

    connection_mode:
      web: cloud
      cloud: cloud
    consent_management:
      web:
        - provider: oneTrust
          consents:
            - marketing

The above example uses the new API with email as the upsert key, and connects web sources in cloud mode, so it omits event_filtering — see Event filtering.

Config keys

config accepts only the keys listed below. The shared config key rules cover unknown keys, defaults, and immutability.

In cloud mode HubSpot accepts identify and track events. In device mode, web sources also send page.

Connection

New API settings

These keys apply when api_version is newApi.

hubspot_events:
  - rs_event_name: Order Completed
    hubspot_event_name: pe12345_order_completed
    event_properties:
      - from: revenue
        to: order_value

Event filtering

Client-side event filtering applies only when connection_mode.web is device — the dashboard shows these controls only then, and the SDK is what applies the filter. Rudder CLI accepts the block in any mode, but events sent in cloud mode reach HubSpot unfiltered.

connection_mode:
  web: device
event_filtering:
  whitelist:
    - Signed Up

Per-source keys

Both keys are objects keyed by the local source type — the tokens listed under Source types. A key naming a source type this destination doesn’t support fails validation.

connection_mode:
  web: device
  cloud: cloud

Source types

HubSpot accepts events from these source types in the mentioned connection modes:

Only web offers device mode, which loads HubSpot’s native script in the browser. See HubSpot device mode and RudderStack Connection Modes.

The dashboard additionally offers HubSpot to AMP, Shopify, and Reverse ETL sources. Rudder CLI doesn’t manage those connections, so amp, shopify, and warehouse are invalid here.

Connect a source

An event stream connection to this destination is checked against two rules at validate time.

The source’s type must be supported. A source’s type resolves to one of the tokens above before the check — a JavaScript source resolves to web, and webhook and server-side SDK sources resolve to cloud. An unsupported type reports:

destination 'hubspot-prod' (type 'hs') does not support source 'my-source':
source type 'amp' is not among supported source types: android, android_kotlin, ...

The destination config must carry a connection_mode entry for that source type. This lives on the destination spec, not on the connection spec. Without it:

destination 'hubspot-prod' config has no 'connection_mode' entry for source type 'web'

HubSpot needs no additional config keys to connect a source of any type, in any mode.

Secrets

access_token and hub_id are the secret keys. Write each as a {{ .VAR }} reference and supply the value at apply time:

config:
  access_token: "{{ .HUBSPOT_ACCESS_TOKEN }}"
  hub_id: "{{ .HUBSPOT_HUB_ID }}"

export RUDDER_HUBSPOT_ACCESS_TOKEN="pat-na1-..."
export RUDDER_HUBSPOT_HUB_ID="12345678"
rudder-cli apply

# or
rudder-cli apply --var-file secrets.vars.yaml

Note that:

• The YAML that rudder-cli import writes may or may not include secret keys. Before you apply, make sure every secret key your configuration needs is present and populated through variable substitution.

See How to Use Variable Substitution in Rudder CLI.

See more

• HubSpot Destination for the private app token, API versions, and event mapping
• Destination Type Reference for Rudder CLI for the rules shared across destination types
• Destination YAML Reference for the spec envelope