Connecter HubSpot à n8n : le guide complet (credentials, node, trigger)

HubSpot est souvent le premier « vrai » CRM d'une PME : gratuit au départ, il concentre vite les contacts, les deals et les tickets de toute l'équipe — et chaque lead saisi à la main, chaque deal mis à jour en retard, devient une occasion perdue. Une étude de Reinartz, Krafft et Hoyer publiée en 2004 dans le Journal of Marketing Research montre d'ailleurs que c'est la mise en œuvre concrète des processus CRM — pas le simple achat de l'outil — qui est associée à une meilleure performance économique (Reinartz et al., 2004). Ce guide couvre l'essentiel : authentification (avec le cas particulier du trigger), node natif, trigger, rate limits, propriétés personnalisées et limites à connaître.

Authentification : trois credentials pour deux usages

n8n propose trois credentials HubSpot, non interchangeables.

Le Private App token : le choix par défaut

Pour un usage interne à un seul compte HubSpot, créez une Private App depuis Settings → Integrations → Private Apps, en cochant précisément les scopes nécessaires : crm.objects.contacts.read et .write pour les contacts, leurs équivalents deals, companies et tickets, et crm.schemas.*.read pour lister les propriétés dynamiquement.

Copiez le token de la carte Access token, puis dans n8n : Credentials → New → HubSpot App Token — pas de flow OAuth ni de refresh token à maintenir. Appliquez les précautions habituelles — scopes minimaux, un token par usage — détaillées dans notre guide sur la sécurisation des credentials API dans n8n.

OAuth2 : pour les cas multi-comptes

Le credential HubSpot OAuth2 sert surtout aux intégrations destinées à plusieurs comptes HubSpot (app de marketplace) ou aux politiques imposant des tokens à durée de vie courte. n8n gère le rafraîchissement automatiquement, mais la configuration initiale est nettement plus lourde, pour un bénéfice nul en usage mono-compte.

Le cas particulier du HubSpot Trigger

Piège classique : le node HubSpot Trigger n'accepte ni le Private App token ni OAuth2. Il s'appuie sur l'API de webhooks de HubSpot, réservée aux apps créées dans un compte développeur (gratuit, distinct de votre compte CRM) : créez-y une app, récupérez l'App ID et la Developer API Key, et renseignez-les dans le credential HubSpot Developer API de n8n. Contre-intuitif, mais à faire une seule fois.

Le node HubSpot : ressources et opérations

Le node HubSpot expose les ressources principales du CRM : Contact, Company, Deal, Ticket, Engagement (plus les listes de contacts et les soumissions de formulaires). Trois opérations reviennent partout.

Créer ou mettre à jour un contact. L'opération Create/Update de la ressource Contact fait un upsert sur l'email : contact existant mis à jour, sinon créé. À privilégier par défaut — elle élimine le risque de doublon qu'un create naïf produirait à chaque webhook rejoué.

Chercher un contact par email. L'opération Search (ou Get par email) vérifie l'existence d'un contact : un node IF route ensuite vers une branche « nouveau lead » ou « client existant ».

Créer un deal dans un pipeline. La ressource Deal attend le pipeline et le deal stage sous leur identifiant interne, pas leur libellé (le stage « Rendez-vous pris » du pipeline par défaut s'appelle appointmentscheduled) — identifiants visibles dans Settings → Objects → Deals → Pipelines. Associez le deal au contact via son ID.

La ressource Engagement consigne notes, appels, emails ou tâches sur la timeline d'un contact — créez-en un à chaque relance automatique, pour que le commercial voie sur la fiche ce que l'automatisation a fait.

Le HubSpot Trigger : réagir aux événements du CRM

Une fois le credential Developer API en place, le trigger s'abonne aux webhooks de HubSpot : contact créé, contact supprimé, propriété modifiée, et leurs équivalents pour les companies et les deals. Deux cas dominent :

• Contact créé → déclencher un enrichissement ou une séquence d'onboarding dès qu'un lead entre dans le CRM, quelle qu'en soit la source.
• Propriété dealstage modifiée → notifier l'équipe quand un deal change d'étape, en filtrant sur la propriété surveillée pour ignorer les modifications anodines.

Contrairement aux triggers n8n en polling, celui-ci est un vrai push (latence de quelques secondes). Sans compte développeur, l'alternative est un Schedule Trigger qui interroge périodiquement les contacts modifiés (propriété lastmodifieddate) — moins réactif, mais sans prérequis.

Rate limits : rester sous les plafonds

L'API HubSpot impose deux plafonds aux Private Apps : un plafond en rafale (de l'ordre de 190 requêtes par 10 secondes sur les plans Pro et Enterprise, moins en dessous) et un plafond quotidien partagé entre les apps du compte. Chaque réponse renvoie l'en-tête X-HubSpot-RateLimit-Remaining ; au-delà, l'API répond en 429. Les endpoints de recherche ont leur propre plafond, plus strict.

Trois parades côté n8n :

1. Les endpoints batch de l'API v3 (/crm/v3/objects/contacts/batch/create…) traitent jusqu'à 100 objets par requête — pour un import initial, c'est 100 fois moins d'appels.
2. Loop Over Items + Wait : découper le lot et insérer une pause entre les paquets — la mécanique décrite dans notre article sur les rate limits d'API dans n8n, avec un node Wait au délai éventuellement dynamique.
3. Retry On Fail activé sur les nodes HubSpot, pour absorber les 429 résiduels.

Propriétés personnalisées

Les propriétés personnalisées se référencent par leur nom interne, visible dans Settings → Properties, pas par leur libellé. Dans le node HubSpot, elles s'ajoutent via les champs Custom Properties. Un node Set juste avant l'appel centralise le mapping entre vos champs source (budget_estime, secteur) et les noms internes.

Ce mapping n'est pas cosmétique : une étude d'Alshawi, Missi et Irani publiée en 2011 dans Industrial Marketing Management montre que la qualité des données clients est l'un des facteurs déterminants — et largement sous-estimés — de l'adoption réussie d'un CRM dans les PME (Alshawi et al., 2011). Un workflow qui écrit dans les mauvaises propriétés ou avec des valeurs non normalisées dégrade silencieusement la donnée de toute l'équipe.

Trois cas d'usage rapides

• Lead entrant → enrichissement → HubSpot : un formulaire ou une campagne Facebook/Instagram Ads déclenche le workflow, un service d'enrichissement complète société et poste, et le contact arrive déjà qualifié — voir notre guide sur l'enrichissement automatique de leads.
• Scoring IA d'un lead : à la création d'un contact (HubSpot Trigger), un LLM évalue le potentiel et écrit un score dans une propriété personnalisée, réutilisable dans les vues et workflows HubSpot — logique détaillée dans la qualification de leads entrants par IA.
• Notification Slack quand un deal avance : le trigger sur dealstage alimente un message Slack avec le montant, l'étape et le lien direct vers le deal — l'équipe suit le pipeline sans vivre dans le CRM.

Les limites du node natif (et l'alternative HTTP Request)

Le node HubSpot couvre le quotidien, pas tout. Pour les recherches complexes, l'endpoint /crm/v3/objects/contacts/search accepte des filterGroups combinant plusieurs critères (AND/OR), du tri et une pagination fine — un contrôle que le node natif n'expose que partiellement. Même chose pour les custom objects ou les endpoints récents : le node HTTP Request, avec votre credential HubSpot en Predefined Credential Type, appelle n'importe quel endpoint sans gérer l'authentification à la main. Règle pratique : node natif d'abord, HTTP Request dès que vous vous battez contre ses options.

Besoin d'aller plus loin — synchroniser HubSpot avec un second CRM ou un outil de facturation, dans les deux sens, sans boucle infinie ? C'est l'objet de notre guide sur la synchronisation CRM HubSpot/Pipedrive avec n8n.

En résumé

Connecter HubSpot à n8n tient en trois briques : un Private App token aux scopes minimaux pour les actions, un credential Developer API séparé pour le trigger, et une gestion des rate limits par batch et node Wait dès que les volumes montent. Le node natif couvre contacts, companies, deals, tickets et engagements avec un upsert par email intégré ; l'HTTP Request prend le relais pour la recherche avancée v3. La suite logique : mettre de l'intelligence dans ce qui entre dans le CRM. Le Pack Inbox IA fournit des workflows prêts à importer qui trient, scorent et routent les demandes entrantes — exactement ce qui mérite d'atterrir dans HubSpot déjà qualifié plutôt que brut.