HubSpot Destination Config Reference

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.

warehouse is the token a Reverse ETL source resolves to. Rudder CLI manages the destination’s warehouse entry — if the destination is connected to a Reverse ETL source, set connection_mode.warehouse: cloud in its spec, or apply removes it.

Rudder CLI can also declare the Reverse ETL connection itself, for the types listed under Supported destinations — see Manage Reverse ETL Connections using Rudder CLI.

The dashboard additionally offers HubSpot to AMP and Shopify sources. Rudder CLI doesn’t manage those connections, so amp and shopify 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. Every type an event stream source can resolve to is supported here, so this check always passes.

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:

• rudder-cli import writes only the secrets the API returns, as {{ .VAR }} references, and leaves the others out. Add any secret key it leaves out, then supply the variables before you apply — see Secrets.

See How to Use Variable Substitution in Rudder CLI.

Changes by release

For changes across every destination type, see Destination Type Changes by Release.

See more

• HubSpot Destination for accepted credential types, API versions, required scopes, and event mapping
• Destination Type Reference for Rudder CLI for the rules shared across destination types
• Destination YAML Reference for the spec envelope