- Outils
- HubSpot
- n8n
- Mise en place
- 1 h
- Niveau
- Intermédiaire
Un message arrive par le formulaire du site, quelqu’un le recopie dans HubSpot, et la demande attend parfois deux jours avant d’exister dans le CRM. Le contact n’a ni source, ni historique, ni relance programmée tant que la saisie n’est pas faite.
Ce guide envoie le formulaire du site directement vers HubSpot : chaque message crée un contact (ou met à jour celui qui existe déjà), sans jeton à créer. Il passe par n8n pour garder un secret côté serveur et être prévenu en cas d’échec. Les étapes suivent la documentation officielle de HubSpot et de n8n, consultée le 7 novembre 2026.

Quelle méthode choisir pour relier un formulaire de site à HubSpot ?
L’aide de HubSpot (« Use non-HubSpot forms », mise à jour le 20/10/2026) décrit deux voies pour les formulaires qui ne sont pas HubSpot. La première est l’outil de collecte des formulaires externes : il repère les balises <form> du site grâce au code de suivi HubSpot. Elle ne marche que sur du HTML statique, avec un champ e-mail, sans formulaire dans une iframe ni chargé après la page, et sans champ masqué. Elle exclut donc la plupart des sites modernes.
La seconde, celle de ce guide, passe par l’API « Submit data to a form ». Elle convient à tout formulaire capable d’envoyer ses champs en JSON, et l’aide de HubSpot la cite pour connecter directement ces formulaires avec l’aide d’un développeur.
Un point de contexte avant de continuer. La documentation de HubSpot indique que depuis le 26 octobre 2026, les applications privées historiques ne peuvent plus être créées (page des applications privées). L’API de soumission de formulaire n’en a pas besoin, ce qui évite le sujet. Elle est classée dans la section « legacy » de la documentation sans annonce de fin de service : relisez cette page au moment de la mise en route.
Étape 1 : préparer un formulaire dans HubSpot
Le contact est créé par un formulaire HubSpot, même s’il n’est jamais affiché : c’est lui qui reçoit les données envoyées.
- Dans HubSpot, ouvrez Marketing, puis Formulaires (« Marketing > Forms »), et créez un formulaire.
- Ajoutez les champs du formulaire du site : au minimum l’adresse e-mail. La documentation de l’API demande de les nommer par leur nom interne, et une demande avec un champ absent du formulaire est refusée (erreur
FIELD_NOT_IN_FORM_DEFINITION). - Dans les options, laissez active la création d’un contact pour chaque nouvelle adresse e-mail. L’article d’aide sur la création de formulaires (mis à jour le 10/09/2026) précise qu’elle crée un contact à chaque adresse inconnue et met à jour la fiche quand l’adresse existe déjà.
- N’activez pas de CAPTCHA sur ce formulaire : la liste d’erreurs de l’API contient
FORM_HAS_RECAPTCHA_ENABLED, qui refuse l’envoi dans ce cas. Le contrôle anti-spam se fait sur le site ou dans n8n.
Étape 2 : relever l’identifiant du compte et celui du formulaire
L’adresse d’envoi contient deux identifiants.
- L’identifiant du compte (Hub ID). Il s’affiche dans le menu du compte en haut à droite et dans l’adresse de HubSpot :
app.hubspot.com/contacts/{HubID}/...(aide, mise à jour le 22/09/2026). La documentation de l’API l’appelleportalId. - L’identifiant du formulaire (GUID). Dans l’éditeur du formulaire, cliquez sur « Review and update », puis « Update », puis « Get embed code » : c’est la valeur de l’attribut
data-form-id. Elle apparaît aussi dans l’adresse de l’éditeur (aide, mise à jour le 05/08/2026). Il faut le droit de modifier les formulaires.
Notez les deux valeurs : elles servent à l’étape 4.
Étape 3 : recevoir le formulaire du site dans n8n
Ajoutez un nœud Webhook. Réglez la méthode sur POST et choisissez une authentification par en-tête (« Header Auth ») : votre site enverra un mot de passe que n8n vérifie, ce qui écarte les appels au hasard. Le nœud accepte aussi d’autres modes, dont l’authentification de base et JWT, selon la documentation du nœud.
Le nœud affiche deux adresses. L’adresse de test fonctionne pendant que vous écoutez un événement de test dans l’éditeur. L’adresse de production n’existe qu’une fois le flux publié, et ses exécutions se lisent dans l’onglet Executions. Au premier passage, envoyez une demande de test à l’adresse de test pour voir la forme des données : les champs du formulaire arrivent dans body, à côté de headers, params et query.
Côté site, le formulaire doit envoyer ses champs en JSON, avec l’en-tête secret, vers l’adresse de production. Un secret placé dans du code exécuté par le navigateur est lisible par tous : s’il n’y a pas de serveur côté site, laissez l’authentification de côté et filtrez dans n8n (étape 5).
Étape 4 : envoyer les champs à HubSpot
Ajoutez un nœud HTTP Request en méthode POST sur l’adresse ci-dessous, en remplaçant les deux identifiants de l’étape 2 :
https://api.hsforms.com/submissions/v3/integration/submit/{portalId}/{formGuid}
Laissez l’authentification à vide : selon la référence de l’API, cette version ne demande aucune authentification. Activez Send Body, choisissez JSON dans Body Content Type et « Using JSON » dans Specify Body (documentation du nœud). Le corps JSON suit la structure de la référence, avec deux blocs :
fields: une ligne par champ, avec trois valeurs.objectTypeIdvaut0-1(les contacts),nameest le nom interne du champ HubSpot (par exempleemailoufirstname),valuereprend la donnée reçue par le webhook, par exemple{{ $json.body.email }}.context:pageUrietpageNameindiquent d’où vient la demande, avec l’adresse et le nom de la page du formulaire. Ils apparaissent dans l’historique du contact et distinguent plusieurs formulaires.
Deux options existent dans la même référence :
context.hutk: la valeur du cookie de suivi de HubSpot (l’exemple de la référence l’appelle « hubspotutk »). Elle rattache la demande aux pages déjà visitées par la personne. Ce cookie relève de votre bandeau de consentement : sans consentement, laissez-le de côté.legalConsentOptions: le texte de consentement et la case cochée par la personne. Recopiez celui de votre formulaire, tel qu’il est affiché.
Étape 5 : prévoir les erreurs
L’API répond 200 quand la demande est prise en compte, avec parfois une adresse de redirection ou un message à afficher défini dans le formulaire. Deux autres réponses sont documentées :
| Réponse | Sens |
|---|---|
| 400 | Validation refusée, avec un type d’erreur par champ |
| 429 | Limite d’appels dépassée : réessayer plus tard |
Dans le cas d’un 400, la liste des erreurs précise le motif : REQUIRED_FIELD, INVALID_EMAIL, FIELD_NOT_IN_FORM_DEFINITION ou FORM_HAS_RECAPTCHA_ENABLED, entre autres. Corrigez le champ ou le formulaire, car renvoyer la même demande donnera la même erreur.
Dans l’onglet Settings du nœud d’envoi, activez Retry On Fail pour absorber les 429, et réglez On Error sur « Continue (using error output) ». Reliez cette sortie à un nœud Gmail ou Slack qui vous envoie le contenu de la demande : un message refusé ne doit pas disparaître en silence. Avant le nœud d’envoi, un nœud If peut aussi écarter les demandes sans adresse e-mail ou dont le champ message contient des liens, premier filtre contre le spam.
Étape 6 : tester et brancher le formulaire du site
Avant de publier, envoyez une demande à l’adresse de test avec votre propre adresse, puis lancez le flux. Vérifiez dans HubSpot que le contact existe, avec la bonne page d’origine. Renvoyez ensuite la même demande : la fiche doit être mise à jour, sans doublon.
Publiez le flux, puis remplacez dans le formulaire du site l’adresse de test par celle de production. Faites un dernier essai depuis le site en ligne, avec une adresse de votre équipe, et lisez l’exécution dans l’onglet Executions.
Et après ?
Quand les contacts arrivent seuls, la suite logique est de les relier au reste de l’entreprise : devis, facturation, ERP. L’article relier son ERP, son CRM et sa comptabilité décrit ces liaisons. Pour le choix de l’outil qui portera le flux, voyez n8n, Make ou du code, et le terme n8n du glossaire.
Ce guide couvre un formulaire, un compte HubSpot et des champs simples. Si les demandes doivent aussi créer une affaire, prévenir le bon commercial selon le secteur ou alimenter un autre logiciel, c’est une automatisation à construire : notre service Automatisation des tâches démarre à 1 900 € HT, et la page intégration HubSpot montre ce que l’API permet d’autre.




