n8n et HubSpot : Synchronisez vos contacts et offres (compte gratuit)

1. Préparation : Connecter n8n à HubSpot

Avant de pouvoir manipuler des données, nous devons établir une connexion sécurisée. La plupart des services modernes, y compris HubSpot, utilisent des tokens d'API pour authentifier les requêtes. Pour HubSpot, la méthode recommandée pour les intégrations personnalisées comme la nôtre est de créer une Application Privée (Private App).

Prérequis

Assurez-vous d'avoir un compte HubSpot. Un compte gratuit est suffisant pour tous les exercices de ce module. Si vous n'en avez pas, vous pouvez en créer un sur hubspot.com.

Étape 1 : Créer une Application Privée dans HubSpot

Une application privée est une configuration dans votre compte HubSpot qui génère un token d'accès unique pour votre usage exclusif.

La vidéo suivante (en anglais) montre précisément comment créer cette application et configurer les autorisations nécessaires.

Voici une image de la page où vous commencerez le processus dans HubSpot.

Les scopes sont cruciaux : ils définissent précisément ce que n8n aura le droit de faire dans votre compte HubSpot. En ne donnant que les permissions nécessaires, vous respectez le principe de moindre privilège, une bonne pratique en matière de sécurité.

Étape 2 : Créer les Identifiants (Credentials) dans n8n

Maintenant que vous avez votre token, il faut le stocker de manière sécurisée dans n8n.

1. Dans votre interface n8n, allez dans le menu de gauche et cliquez sur Credentials.
2. Cliquez sur Add Credential.
3. Recherchez "HubSpot" et sélectionnez HubSpot API.
4. Dans le champ Access Token, collez le token que vous avez copié depuis votre application privée HubSpot.
5. Donnez un nom à cet identifiant (ex: "Mon HubSpot Pro").
6. Cliquez sur Save. n8n testera la connexion et devrait afficher "Connection successful!".

Votre n8n est maintenant prêt à communiquer avec HubSpot !

2. Exercice : Créer et Récupérer des Données dans HubSpot

Nous allons maintenant construire un workflow simple pour illustrer les opérations de base : la création d'un contact, puis la création d'une transaction (deal) associée à ce contact.

L'article suivant est une excellente référence qui liste les nombreuses actions possibles avec le nœud HubSpot. Nous allons en utiliser quelques-unes.

Étape A : Créer un Nouveau Contact

Commençons par créer un workflow qui ajoute un contact à votre base de données HubSpot.

1. Créez un nouveau workflow et ajoutez un nœud Manual Trigger (ou laissez le nœud Start).
2. Ajoutez un nœud HubSpot après le déclencheur.
3. Configurez le nœud HubSpot :
   • Credential for HubSpot API: Sélectionnez l'identifiant que vous venez de créer.
   • Resource: Contact.
   • Operation: Create or Update. Cette opération est très pratique car elle crée le contact s'il n'existe pas (basé sur l'email) ou le met à jour s'il existe déjà, évitant ainsi les doublons.
   • Email: laura.tech@n8n-learner.com
   • Cliquez sur Add Property. Dans la liste déroulante, sélectionnez First Name, et dans le champ de valeur, entrez Laura.
   • Répétez l'opération pour ajouter une propriété Last Name avec la valeur Tech.
4. Exécutez le nœud (Execute node).
5. Vérification: Allez dans votre compte HubSpot, section Contacts. Vous devriez y trouver le nouveau contact "Laura Tech".

Étape B : Récupérer un Contact et Créer une Transaction (Deal) Associée

Maintenant, construisons un flux un peu plus réaliste. Nous allons créer un contact, puis utiliser son ID pour lui associer une nouvelle transaction.

1. Gardez le nœud HubSpot configuré pour créer le contact. Nous allons l'enchaîner.
2. Ajoutez un deuxième nœud HubSpot après le premier.
3. Configurez ce deuxième nœud pour créer une transaction :
   • Credential: Le même que précédemment.
   • Resource: Deal.
   • Operation: Create.
   • Deal Name: Projet d'automatisation pour Laura
   • Cliquez sur Add Field et sélectionnez Deal Stage. Pour la valeur, vous devez utiliser l'ID d'une étape de votre pipeline de transactions. Allez dans votre HubSpot, dans les paramètres de transactions, et copiez l'ID interne d'une étape (par exemple, "Appointment Scheduled" a souvent l'ID appointmentscheduled). Entrez cet ID.
   • Associations: C'est ici que la magie opère. Cliquez sur Add Association.
     • To Object Type: Contact.
     • To Object Id: Nous allons ici utiliser une expression pour récupérer dynamiquement l'ID du contact créé à l'étape précédente. Cliquez dans le champ et utilisez le sélecteur de variables pour pointer vers la sortie du premier nœud HubSpot : {{ $json["id"] }}.

Votre workflow devrait maintenant avoir deux nœuds HubSpot à la suite. Le premier crée un contact, et le second crée une transaction en utilisant l'ID du contact fraîchement créé pour les lier.

4. Exécutez le workflow complet en cliquant sur Execute Workflow.
5. Vérification: Retournez dans HubSpot. Vous devriez voir la nouvelle transaction "Projet d'automatisation pour Laura" dans votre pipeline de ventes. Si vous ouvrez cette transaction, vous verrez que le contact "Laura Tech" y est bien associé.

3. Solution Complète

Voici le code JSON du workflow final que vous pouvez copier et coller dans n8n pour comparer avec votre travail. N'oubliez pas d'assigner votre propre identifiant HubSpot dans les deux nœuds.

{
  "name": "Création Contact et Deal HubSpot",
  "nodes": [
    {
      "parameters": {},
      "name": "Start",
      "type": "n8n-nodes-base.start",
      "typeVersion": 1,
      "position": [
        250,
        300
      ]
    },
    {
      "parameters": {
        "resource": "contact",
        "operation": "createOrUpdate",
        "email": "laura.tech@n8n-learner.com",
        "properties": {
          "property": [
            {
              "name": "firstname",
              "value": "Laura"
            },
            {
              "name": "lastname",
              "value": "Tech"
            }
          ]
        }
      },
      "name": "Create Contact",
      "type": "n8n-nodes-base.hubSpot",
      "typeVersion": 4,
      "position": [
        470,
        300
      ],
      "credentials": {
        "hubSpotApi": {
          "id": "YOUR_CREDENTIAL_ID",
          "name": "HubSpot Credential"
        }
      }
    },
    {
      "parameters": {
        "resource": "deal",
        "name": "Projet d'automatisation pour Laura",
        "properties": {
          "property": [
            {
              "name": "dealstage",
              "value": "appointmentscheduled"
            }
          ]
        },
        "associations": {
          "association": [
            {
              "toObjectType": "contact",
              "toObjectId": "={{ $json.id }}"
            }
          ]
        }
      },
      "name": "Create Associated Deal",
      "type": "n8n-nodes-base.hubSpot",
      "typeVersion": 4,
      "position": [
        690,
        300
      ],
      "credentials": {
        "hubSpotApi": {
          "id": "YOUR_CREDENTIAL_ID",
          "name": "HubSpot Credential"
        }
      }
    }
  ],
  "connections": {
    "Start": {
      "main": [
        [
          {
            "node": "Create Contact",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Create Contact": {
      "main": [
        [
          {
            "node": "Create Associated Deal",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  }
}

Conclusion

Félicitations ! Vous avez franchi une étape majeure en connectant n8n à un service externe critique et en manipulant ses données.

Points clés à retenir :

• La connexion à des services SaaS comme HubSpot se fait de manière sécurisée via des Applications Privées et des tokens d'accès.
• La gestion des permissions via les scopes est une pratique de sécurité essentielle.
• Le nœud HubSpot de n8n abstrait la complexité de l'API et propose une interface claire basée sur des Ressources (Contact, Deal) et des Opérations (Create, Get, etc.).
• L'enchaînement de nœuds et l'utilisation d'expressions permettent de créer des flux de données dynamiques, comme l'association d'une transaction à un contact nouvellement créé.

Vous maîtrisez maintenant les opérations de création et de lecture. Dans la prochaine leçon, nous compléterons ce cycle en apprenant à mettre à jour des enregistrements CRM existants en utilisant un identifiant connu, une opération indispensable pour maintenir la cohérence de vos données.