HubSpot

CRM and marketing automation platform for inbound marketing, sales, and customer service with unified contact management.

⚠️

This integration is currently in beta. Configuration and behaviour may change.

Prerequisites

Complete these steps in HubSpot before configuring Signal.

Access your HubSpot account

Log in to HubSpot at app.hubspot.com. If you do not have an account, sign up for a HubSpot plan that includes API access (Professional or Enterprise).

Find your Portal ID

Your Portal ID (also called Hub ID) is displayed in the top-right corner of the HubSpot dashboard, next to your account name. It is also visible in your HubSpot dashboard URL (e.g. app.hubspot.com/contacts/12345678). Copy this number.

Create a Private App for API access

Navigate to Settings > Integrations > Private Apps. Click Create a Private App. Fill in the details:

Give the app a name (e.g. “Datafly Signal”).
Under Scopes, grant the following permissions:
- crm.objects.contacts.write — for creating and updating contacts
- crm.objects.contacts.read — for reading contact data
- crm.objects.deals.write — for creating deals (if using deal tracking)
- analytics.read — for event tracking
Click Create App and confirm.
Copy the Access Token that is displayed. This token does not expire but can be revoked.

Note your Pipeline ID (optional)

If you want to associate events with a specific deal pipeline, navigate to Settings > Objects > Deals > Pipelines. Select the pipeline and note its Pipeline ID from the URL or settings. Leave this empty to use the default pipeline.

Configuration

Field	Type	Required	Description
`access_token`	secret	Yes	A HubSpot Private App access token. Created in Settings > Integrations > Private Apps.
`portal_id`	string	Yes	Your HubSpot Portal ID (Hub ID). Found in the top-right of the dashboard.
`pipeline_id`	string	No	The deal pipeline ID to associate events with. Leave empty for the default pipeline.

Signal Setup

Quick Setup

Navigate to Integrations in the sidebar.
Open the Integration Library tab.
Find HubSpot or filter by CDP.
Click Install, and fill in the required fields with the credentials gathered above.
Click Install Integration to create the integration with a ready-to-use default configuration.

API Setup

curl -X POST http://localhost:8084/v1/admin/integration-catalog/hubspot/install \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HubSpot",
    "variant": "default",
    "config": {
      "access_token": "pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "portal_id": "12345678",
      "pipeline_id": "default"
    },
    "delivery_mode": "server_side"
  }'

Event Mapping

Signal events are mapped to HubSpot API calls as follows:

Signal Event	HubSpot Concept	Notes
`page`	Behavioural event	Page view data sent as a custom behavioural event on the contact timeline
`track`	Custom behavioural event	Event name and properties forwarded as custom behavioural events
`identify`	Contact create/update	Email and traits used to create or update HubSpot contacts via the CRM API
`track` (purchase)	Deal creation	Purchase events can create deals in the specified pipeline with revenue data

HubSpot identifies contacts primarily by email address. Ensure your Signal events include an email property for proper contact matching.

Delivery

Events are delivered server-side from your Datafly Signal infrastructure directly to the HubSpot API. No client-side scripts are loaded for this integration.

Testing

After installing the integration, trigger a test event from your website or via the Signal event API.
In HubSpot, navigate to Contacts and search for the test user by email to verify the contact was created or updated.
Click into the contact record and check the Activity timeline for the events sent from Signal.
In Signal, check the Live Events view to confirm the event was delivered with a 200 response status.

Troubleshooting

Symptom	Possible Cause	Resolution
`401 Unauthorized`	Invalid or revoked access token	Create a new Private App or regenerate the token in HubSpot Settings > Integrations > Private Apps
`403 Forbidden`	Insufficient scopes	Edit the Private App and add the required scopes, then copy the updated token
Contact not created	Missing email	HubSpot requires an email address to create contacts. Ensure events include an email property
`429 Too Many Requests`	Rate limit exceeded	HubSpot applies rate limits per Private App. Reduce event volume or contact HubSpot support
Wrong pipeline	Incorrect pipeline ID	Verify the pipeline ID in HubSpot Settings > Objects > Deals > Pipelines

Visit HubSpot documentation for full API reference and Private App setup details.

Hightouch Iterable