Connectez une API avec HTTP Request

Au chapitre précédent, vous avez normalisé les tickets provenant de trois canaux. Vous disposez maintenant d'un ticket propre avec, entre autres, un champout_customer_email. Pour chaque ticket entrant, vous allez interroger HubSpot afin de savoir qui est ce client (son plan tarifaire, son entreprise, sa date d'inscription).

Lisez une documentation d'API pour préparer votre requête

Avant de brancher quoi que ce soit dans n8n, vous devez comprendre ce que vous allez appeler.

Quand vous ouvrez une documentation pour la première fois, cherchez quatre informations :

1. L'adresse (l'endpoint) : l'URL à appeler, par exemplehttps://api.hubapi.com/crm/2026-03contacts.

2. La méthode HTTP : ce que vous voulez faire (GETpour lire des données,POSTpour en créer,PATCHpour en modifier).

3. Les paramètres : les informations à transmettre (un email, un identifiant, des filtres).

4. L'authentification : ce qui prouve que vous avez le droit d'appeler ce service.

Dans notre cas, l'API HubSpot propose un endpoint de recherche de contacts par email. Vous lui transmettez l'email du ticket (out_customer_email), et elle vous renvoie la fiche du contact correspondant, si elle existe.

Récapitulons tout cela en vidéo :

Authentifiez-vous auprès d'une API avec les credentials n8n

Pour appeler un service externe, vous devez prouver que vous en avez l'autorisation. Il existe deux mécanismes courants :

1. La clé d'API (API Key / Token) : un code secret que vous transmettez à chaque appel, souvent dans un en-tête HTTP (Authorization: Bearer votre_token). C'est le mécanisme utilisé par HubSpot avec les Private App tokens.

2. OAuth 2.0 : un protocole plus complexe qui permet à un utilisateur de vous autoriser sans jamais vous communiquer son mot de passe. Vous le rencontrerez surtout avec Google, Slack, ou Microsoft.

Pour HubSpot, vous allez créer une Private App dans votre compte sandbox et récupérer un token d'accès.

Structurez une requête HTTP dynamique dans n8n

Une fois votre credential créé, vous pouvez configurer le nœud HTTP Request. Pour chercher un contact dans HubSpot à partir de son email, configurez le nœud comme suit :

• Method :POST

• URL :https://api.hubapi.com/crm/v3/objects/contacts/search

• Authentication : sélectionnez votre credential HubSpot

• Body (JSON) : transmettez un objet de recherche qui utiliseout_customer_emailcomme valeur de filtre, et listez uniquement les propriétés dont vous avez besoin (firstname,lastname,company,plan,createdate).

C'est le champvaluedu filtre qui rend la requête dynamique : à chaque ticket entrant, n8n y injecte l'email du ticket avant d'envoyer l'appel. Sans cette injection, vous appelleriez toujours HubSpot avec le même email en dur (ce qui ne servirait à rien).

Maintenant, voyons ça directement en image :

Interprétez les codes HTTP pour réagir au bon moment

Chaque réponse d'une API est accompagnée d'un code numérique qui indique si l'appel a réussi ou non. Voici les familles à connaître :

Ces codes vont devenir votre boussole dans la partie 2 de ce cours, au chapitre “Gérez les erreurs, les retries et les cas limites”, quand vous mettrez en place la gestion des erreurs.

Parsez la réponse JSON pour n'extraire que les champs utiles

HubSpot vous renvoie un objet JSON qui peut contenir de nombreux champs. Pour notre pipeline, vous n'avez besoin que de quelques informations : le prénom, le nom, l'entreprise, le plan et la date de création du compte.

La réponse de l'API ressemble à ceci :

{
  "results": [{
    "id": "12345",
    "properties": {
      "firstname": "Marie",
      "lastname": "Dupont",
      "company": "Acme SaaS",
      "plan": "Pro",
      "createdate": "2023-04-12T08:30:00Z"
    }
  }]
}

Pour accéder au prénom dans une expression n8n, vous écrirez :{$json.results[0].properties.firstname}.

Après le nœud HTTP Request, ajoutez un nœud Edit Fields pour renommer ces données en suivant votre convention de nommage :

• out_client_name← prénom + nom concaténés

• out_client_company←results[0].properties.company

• out_client_plan←results[0].properties.plan

• out_client_since←results[0].properties.createdate

À vous de jouer !

Consigne

Revenons à notre projet de workflow pour AgroTech !

Reprenez le pipeline construit lors de l'exercice du chapitre précédent (relevés normalisés avec out_device_email)  . Ajoutez une étape qui :

1. Interroge l'API HubSpot avec l'email/identifiant du capteur ou du responsable (  out_device_email  ) pour retrouver la fiche de l'exploitation agricole.

2. Extrait les informations utiles : nom de l'exploitant, nom de la ferme/exploitation, type de culture/abonnement, date d'enregistrement du capteur/compte.

3. Enrichit le relevé avec ces informations, en suivant la convention  out_farm_*  pour les nouveaux champs.

• out_farm_owner  : prénom + nom du responsable (ou null si introuvable)

• out_farm_name  : nom de l'exploitation / ferme (ou null)

• out_farm_crop_type  : type de culture ou formule (ex: "Viticulture Premium", "Maraîchage Bio") (ou null)

• out_farm_registered_since  : date d'enregistrement au format ISO (ou null)

• Tous les champs  out_*  du chapitre précédent (  out_source  ,  out_subject  ,  out_message  ,  out_device_email  ,  out_priority  ,  out_created_at  ) sont conservés.

Contrainte : Si aucun contact/exploitation n'est trouvé(e) dans HubSpot pour cet email, tous les champs  out_farm_*  doivent valoir null(ne faites pas planter le workflow).

Corrigé

Voici un exemple de ce que vous pouviez faire pour y arriver :

Description de la capture d'écran :

• Structure du workflow (sur fond marron) :

  • Nœud de déclenchement : 'When clicking Test workflow'.

  • Nœud 1 : 'Simuler relevé normalisé' (génère des données de test).

  • Nœud 2 : 'Rechercher Exploitation HubSpot' (requête POST à l’API HubSpot).

  • Nœud 3 : 'Enrichir Relevé Agricole - Edit Fields' (modifie les champs du relevé).

  • Nœud 4 : 'Enrichir Relevé Agricole - Code JS' (ajoute des champs via JavaScript).

• Description textuelle à gauche :

  • Entrée : Relevé agricole normalisé (source, sujet, message, email, priorité, date).

  • Traitement : Recherche du contact/exploitation lié àout_device_emailvia l’API HubSpot.

  • Sortie : Objet enrichi avec des champs commeout_farm_owner,out_farm_name, etc.

• Logs (en bas) : Exécution réussie en 1253ms pour tous les nœuds.

• Bouton : 'Execute workflow' en orange, prêt à être cliqué.

Capture d’écran des paramètres du nœud 'Rechercher Exploitation HubSpot' dans un workflow n8n :

• Onglet Parameters ouvert :

  • Method : POST.

  • URL :https://api.hubspot.com/crm/v3/objects/contacts/search.

  • Authentication : Bearer Auth avec le tokenn8n-test-api-hubspot.

  • Send Headers : Activé, avec un headerContent-Type: application/json.

• Input (à gauche) : Données normalisées avec les champs :

  • out_source: Station Météo Web

  • out_subject: Risque de Gel

  • out_message: Chute de température brutale sous 0°C

  • out_device_email: emailmaria@hubspot.com

  • out_priority: high

  • out_created_at: 2026-03-15T06:00:00Z.

• Output (à droite) : Résultat de la requête HubSpot avec :

  • id: 811076535496

  • properties: email, firstname (Maria), lastname (Johnson), hs_object_id, etc.

  • url: <https://app-eu1.hubspot.com/contacts/148805580/record/0-1/811076535496>.

En résumé

• Le nœud HTTP Request vous permet d'appeler n'importe quelle API depuis n8n, vous n'êtes pas limité aux nœuds natifs.

• Avant de coder, lisez la documentation : identifiez l'adresse, la méthode, les paramètres et le mécanisme d'authentification.

• Stockez toujours vos tokens dans les Credentials n8n, jamais dans un champ de nœud.

• Les codes HTTP vous indiquent si l'appel a réussi, et que faire si ce n'est pas le cas.

• Après chaque appel, rennommez les données utiles avec votre conventionout_pour que la suite du pipeline reste lisible.

Dans le prochain chapitre, vous allez ouvrir un autre canal d'entrée pour votre pipeline : les webhooks. Plutôt que d'attendre qu'un formulaire soit soumis, votre workflow sera déclenché en temps réel dès qu'un outil externe vous envoie une notification.