● Contexte
Enrichir un contact HubSpot a l'air simple, jusqu'à ce que vous vouliez que ce soit gratuit, que les utilisateurs puissent apporter leurs propres clés API, que ça reste sécurisé, et que ça demeure malgré tout fluide dans le CRM.
Ce projet est notre réponse : un outil HubSpot qui orchestre plusieurs fournisseurs d'enrichissement en cascade tout en gardant une UX limpide et les parties sensibles verrouillées.
Stack technique : ce dont vous avez besoin
- Projet HubSpot auto-déployé
- CRM Card + page Réglages (React + TypeScript)
- Services d'enrichissement en cascade (Full Enrich → Zeliq → Kaspr), avec une complexité accrue quand les résultats reviennent par webhook
Le défi consistait à livrer un outil HubSpot gratuit qui permette aux utilisateurs de brancher leurs propres clés API pour plusieurs services d'enrichissement, tout en gardant l'expérience simple et l'implémentation sécurisée.
Le plus difficile était d'enchaîner les fournisseurs en fonction de ce qui est configuré et disponible, sans exposer la moindre complexité à l'utilisateur qui déclenche la demande d'enrichissement.
● Explications
Projet HubSpot & auto-déploiement
Nous avons construit l'application HubSpot avec le système d'apps déclaratif le plus récent de HubSpot. Le projet est défini dans un fichier JSON stocké sur GitHub et auto-déployé vers HubSpot à chaque mise à jour. Cela nous apporte l'automatisation de la configuration, ainsi que de la traçabilité et de la reproductibilité : chaque action est enregistrée et historisée, ce qui réduit les erreurs humaines et améliore la collaboration.
L'application exploite aussi les capacités plus récentes de HubSpot, dont une page Réglages entièrement personnalisée. C'est là que les utilisateurs peuvent saisir les clés API des services d'enrichissement qu'ils souhaitent utiliser, et les voir affichées de façon obfusquée (récupérées depuis notre propre base de données).
CRM Card & Réglages en React / TypeScript
Dans l'environnement HubSpot, nous avons construit les deux :
- la CRM Card (affichée sur la fiche du contact), et
- la page Réglages, en React + TypeScript.
React gère l'état de l'interface et les interactions, tandis que TypeScript réduit les erreurs de développement en imposant la justesse du typage. HubSpot exécute ce code d'interface dans un environnement dédié et isolé : nous n'accédons qu'à l'interface et à un ensemble limité de données liées au contact. Ce dispositif permet de garder une expérience hautement personnalisée tout en restant sûr.
Cette architecture facilite aussi l'interfaçage avec notre propre base de données via des API sécurisées, tout en profitant de la couche d'isolation supplémentaire de HubSpot.
Backend : du « n8n d'abord » à un service NodeJS dédié
Nous avons d'abord envisagé de tout gérer dans n8n, mais les exigences de l'outil ont vite rendu cette approche plus difficile à faire évoluer. Il nous fallait, entre autres :
- Validation des appels HubSpot : HubSpot inclut une signature cryptographique sur chaque appel. Nous la validons pour garantir que les requêtes proviennent réellement de HubSpot. C'est essentiel pour empêcher tout accès malveillant aux données sensibles, et cela aide aussi à identifier quelle instance HubSpot nous appelle (afin de décoder les bonnes clés API).
- Workflow d'authentification HubSpot : requis lors de la connexion de l'application à une nouvelle instance HubSpot, et utilisé pour reporter les changements dans HubSpot (par exemple, écrire le téléphone/e-mail trouvé par l'enrichissement).
- Chiffrement des clés API : comme nous stockons des clés par instance, elles sont stockées chiffrées dans MongoDB en AES-256.
- Orchestration de l'enrichissement en cascade : abordée dans la section suivante.
Pour ces raisons, nous avons mis en place un service NodeJS dédié pour gérer l'ensemble du périmètre backend sans sur-ingénierie. Dans n8n, cela aurait été possible, mais aurait nécessité plusieurs workflows partageant des fonctions et de la logique, le rendant moins maintenable et plus difficile à tester dans le temps.
Services d'enrichissement en cascade
Enchaîner des fournisseurs d'enrichissement soulève quelques défis clés : décider quels services sont disponibles, gérer les erreurs propres à chaque fournisseur, et composer avec des réponses qui peuvent être asynchrones. Par exemple, Full Enrich peut ne pas répondre immédiatement ; il rappelle plus tard via webhook une fois les résultats prêts.
Pour gérer cela, nous traitons chaque demande d'enrichissement comme un flux avec :
- une étape d'avancement,
- quel service a été utilisé,
- quelle réponse a été reçue,
- et quelle devrait être l'étape suivante.
Quand un fournisseur renvoie un résultat, il inclut une « signature » qui nous permet de le rattacher au bon flux, afin de soit continuer vers le service suivant (si nécessaire), soit mettre à jour HubSpot si le résultat est bon.
Côté interface, la CRM card interroge périodiquement le statut du flux et se met à jour automatiquement dès qu'une réponse valide arrive. Elle indique aussi quel fournisseur a produit le résultat.
● Conclusion
Le résultat final
Un outil HubSpot gratuit qui permet aux utilisateurs de brancher leurs propres clés API pour lancer l'enrichissement de contacts en toute sécurité. Ce projet offre une expérience d'enrichissement simple, « en un clic », au sein du CRM, tout en masquant toutes les parties ardues derrière une architecture propre : une CRM card et une page Réglages en React/TypeScript côté front, et un service NodeJS dédié côté back pour valider les signatures HubSpot, gérer l'OAuth, chiffrer les clés (AES-256) et orchestrer la cascade d'enrichissement.