Connecting HubSpot to n8n: the complete guide (credentials, node, trigger)

HubSpot is often an SMB's first "real" CRM: free to start with, it quickly concentrates the whole team's contacts, deals, and tickets — and every lead typed in by hand, every deal updated late, becomes a missed opportunity. A study by Reinartz, Krafft, and Hoyer published in 2004 in the Journal of Marketing Research shows that it is the concrete implementation of CRM processes — not the mere purchase of the tool — that is associated with better economic performance (Reinartz et al., 2004). This guide covers the essentials: authentication (with the trigger's special case), the native node, the trigger, rate limits, custom properties, and the limitations to know.

Authentication: three credentials for two use cases

n8n offers three HubSpot credentials, and they are not interchangeable.

The Private App token: the default choice

For internal use on a single HubSpot account, create a Private App from Settings → Integrations → Private Apps, checking precisely the scopes you need: crm.objects.contacts.read and .write for contacts, their deals, companies, and tickets equivalents, and crm.schemas.*.read to list properties dynamically.

Copy the token from the Access token card, then in n8n: Credentials → New → HubSpot App Token — no OAuth flow, no refresh token to maintain. Apply the usual precautions — minimal scopes, one token per use case — detailed in our guide on securing API credentials in n8n.

OAuth2: for multi-account scenarios

The HubSpot OAuth2 credential is mainly for integrations meant for multiple HubSpot accounts (a marketplace app) or policies mandating short-lived tokens. n8n handles the refresh automatically, but the initial setup is significantly heavier, for zero benefit in a single-account setup.

The HubSpot Trigger's special case

A classic trap: the HubSpot Trigger node accepts neither the Private App token nor OAuth2. It relies on HubSpot's webhooks API, reserved for apps created in a developer account (free, separate from your CRM account): create an app there, retrieve the App ID and the Developer API Key, and enter them in n8n's HubSpot Developer API credential. Counter-intuitive, but done only once.

The HubSpot node: resources and operations

The HubSpot node exposes the CRM's main resources: Contact, Company, Deal, Ticket, Engagement (plus contact lists and form submissions). Three operations come up everywhere.

Creating or updating a contact. The Contact resource's Create/Update operation performs an upsert on the email: an existing contact is updated, otherwise it is created. Favor it by default — it eliminates the duplicate risk a naive create would produce on every replayed webhook.

Searching for a contact by email. The Search operation (or Get by email) checks whether a contact exists: an IF node then routes to a "new lead" or "existing customer" branch.

Creating a deal in a pipeline. The Deal resource expects the pipeline and the deal stage by their internal identifier, not their label (the default pipeline's "Appointment scheduled" stage is called appointmentscheduled) — identifiers visible in Settings → Objects → Deals → Pipelines. Associate the deal with the contact via its ID.

The Engagement resource logs notes, calls, emails, or tasks on a contact's timeline — create one for every automated follow-up, so the sales rep sees on the record what the automation did.

The HubSpot Trigger: reacting to CRM events

Once the Developer API credential is in place, the trigger subscribes to HubSpot's webhooks: contact created, contact deleted, property changed, and their equivalents for companies and deals. Two cases dominate:

• Contact created → trigger an enrichment or onboarding sequence as soon as a lead enters the CRM, whatever its source.
• dealstage property changed → notify the team when a deal changes stage, filtering on the watched property to ignore trivial edits.

Unlike n8n's polling triggers, this one is a true push (latency of a few seconds). Without a developer account, the alternative is a Schedule Trigger that periodically queries modified contacts (the lastmodifieddate property) — less reactive, but with no prerequisites.

Rate limits: staying under the caps

The HubSpot API imposes two caps on Private Apps: a burst cap (around 190 requests per 10 seconds on Pro and Enterprise plans, less below) and a daily cap shared across the account's apps. Every response returns the X-HubSpot-RateLimit-Remaining header; beyond the limit, the API responds with a 429. The search endpoints have their own, stricter cap.

Three countermeasures on the n8n side:

1. The batch endpoints of the v3 API (/crm/v3/objects/contacts/batch/create…) process up to 100 objects per request — for an initial import, that's 100 times fewer calls.
2. Loop Over Items + Wait: split the batch and insert a pause between chunks — the mechanism described in our article on API rate limits in n8n, with a Wait node whose delay can even be dynamic.
3. Retry On Fail enabled on the HubSpot nodes, to absorb residual 429s.

Custom properties

Custom properties are referenced by their internal name, visible in Settings → Properties, not by their label. In the HubSpot node, they are added via the Custom Properties fields. A Set node right before the call centralizes the mapping between your source fields (estimated_budget, industry) and the internal names.

This mapping is no cosmetic detail: a study by Alshawi, Missi, and Irani published in 2011 in Industrial Marketing Management shows that customer data quality is one of the decisive — and widely underestimated — factors in successful CRM adoption in SMEs (Alshawi et al., 2011). A workflow that writes to the wrong properties or with non-normalized values silently degrades the data the whole team relies on.

Three quick use cases

• Inbound lead → enrichment → HubSpot: a form or a Facebook/Instagram Ads campaign triggers the workflow, an enrichment service fills in company and job title, and the contact arrives already qualified — see our guide on automatic lead enrichment.
• AI lead scoring: on contact creation (HubSpot Trigger), an LLM assesses the potential and writes a score to a custom property, reusable in HubSpot's views and workflows — the logic is detailed in AI qualification of inbound leads.
• Slack notification when a deal moves: the trigger on dealstage feeds a Slack message with the amount, the stage, and a direct link to the deal — the team follows the pipeline without living inside the CRM.

The native node's limits (and the HTTP Request alternative)

The HubSpot node covers the day-to-day, not everything. For complex searches, the /crm/v3/objects/contacts/search endpoint accepts filterGroups combining multiple criteria (AND/OR), sorting, and fine-grained pagination — a level of control the native node only partially exposes. Same story for custom objects or recent endpoints: the HTTP Request node, with your HubSpot credential as a Predefined Credential Type, calls any endpoint without handling authentication by hand. Practical rule: native node first, HTTP Request as soon as you find yourself fighting its options.

Need to go further — synchronizing HubSpot with a second CRM or a billing tool, in both directions, without infinite loops? That is the subject of our guide on HubSpot/Pipedrive CRM synchronization with n8n.

Summary

Connecting HubSpot to n8n comes down to three building blocks: a Private App token with minimal scopes for actions, a separate Developer API credential for the trigger, and rate limit management through batching and the Wait node as volumes grow. The native node covers contacts, companies, deals, tickets, and engagements with a built-in upsert by email; HTTP Request takes over for advanced v3 search. The logical next step: putting intelligence into what enters the CRM. The AI Inbox Pack provides ready-to-import workflows that sort, score, and route inbound requests — exactly what deserves to land in HubSpot already qualified rather than raw.