Faire des appels API côté serveur sur HubSpot, c’est possible et même recommandé, quand on veut sécuriser ses requêtes, éviter d’exposer des secrets côté client ou exécuter des logiques métier plus complexes. Depuis l’arrivée des serverless functions sur le CMS HubSpot, les possibilités se sont nettement élargies… mais elles ne sont pas sans contraintes.
Vous êtes développeur Hubspot, tech lead, ou intégrateur marketing ?
Vous cherchez à connecter HubSpot à un système externe sans ouvrir trop de portes côté front ?
Cet article vous guide précisément sur ce que vous pouvez faire, comment et surtout jusqu’où vous pouvez aller avant de heurter les vraies limites de la plateforme.
Pourquoi faire des appels API côté serveur sur HubSpot ?
Sécurité des données et exposition front : un risque à éviter
Faire transiter des appels API via le navigateur revient à exposer potentiellement des secrets d’authentification (jetons, clés API), ou à laisser une partie de votre logique métier visible et modifiable. C’est non seulement un risque en termes de sécurité, mais aussi une faille RGPD évidente si des données sensibles sont en jeu. Les fonctions serverless permettent au contraire d’exécuter le code côté serveur, dans un environnement isolé et sécurisé, sans rien exposer au client.
Cas d’usage fréquents : enrichissement CRM, synchronisation de données, formulaires avancés
Ce modèle s’adapte parfaitement à plusieurs cas d’usage critiques :
- Enrichissement CRM : appeler une API tierce (Clearbit, Societeinfo…) pour compléter automatiquement une fiche contact.
- Synchronisation de données : connecter HubSpot à un ERP, une base de données métier, ou un outil d’analytics.
- Formulaires avancés : valider des champs dynamiques, transformer des réponses, ou déclencher des traitements personnalisés à la soumission.
L’intérêt est clair : gagner en puissance, en flexibilité et en sécurité, sans pour autant sortir de l’écosystème HubSpot.
Fonctions serverless sur HubSpot CMS : comment ça marche
Définition et fonctionnement général
Les fonctions serverless de HubSpot permettent d’exécuter du JavaScript côté serveur, directement dans l’environnement HubSpot. Cela signifie que vous pouvez effectuer des appels API, manipuler des données sensibles, ou intégrer des services externes sans jamais exposer de logique ou de secrets côté client.
Ces fonctions sont exécutées à la volée, lorsqu’un point de terminaison est appelé depuis votre site ou votre application. Le tout, sans serveur à maintenir ni backend à déployer. Un fonctionnement léger, rapide et 100 % intégré au CMS HubSpot.
Création d’une fonction : structure, fichiers clés et déploiement
Une fonction serverless se compose d’un petit dossier .functions, avec trois fichiers essentiels :
- function.js : votre code JavaScript (Node.js)
- serverless.json : configuration de la fonction (chemin, nom, secrets, endpoint)
- package.json (optionnel) : gestion des dépendances si vous utilisez un projet développeur
Deux méthodes de création sont possibles :
- Via le Design Manager (méthode historique) : limité, sans dépendances tierces
- Via un projet développeur (recommandé) : permet d’ajouter des packages NPM, de gérer les fonctions localement et de les déployer avec l’ILC
Une fois la fonction prête, elle est exposée à une URL spécifique et peut être appelée depuis un module, un formulaire, ou une action front.
Authentification sécurisée via app privée ou secrets
Pour authentifier vos appels API dans une fonction serverless, deux options :
- Token d’application privée : idéal si vous développez via un projet développeur
- Secrets HubSpot : à créer et référencer dans le serverless.json pour sécuriser une clé API ou un token
Attention à ne jamais renvoyer un secret dans la réponse ni le consigner avec console.log. Même côté serveur, la sécurité de vos données reste prioritaire.
Appels API dans les fonctions serverless : ce qu’il faut savoir
Utilisation standard : fetch / axios côté serveur
Dans une fonction serverless sur HubSpot, vous pouvez utiliser fetch (disponible nativement) ou intégrer axios (via package.json dans un projet développeur) pour effectuer des appels API. C’est la méthode idéale pour :
- envoyer des données à un système tiers après soumission d’un formulaire,
- récupérer des infos enrichies à injecter dynamiquement dans le CMS,
- mettre à jour automatiquement des enregistrements CRM.
L’appel se fait côté serveur, donc sécurisé : vos clés API ou tokens ne transitent jamais vers le navigateur.
Respect des quotas HubSpot : éviter les erreurs 429
Chaque compte est soumis à des quotas stricts d’appels API (par seconde et par jour), selon le niveau d’abonnement et le type d’application (privée ou publique). Si vous les dépassez :
- HubSpot retourne une erreur 429 (Rate Limit Exceeded),
- l’exécution échoue et les données ne sont pas traitées.
Bonnes pratiques :
- toujours gérer les erreurs (try/catch) et prévoir un fallback,
- monitorer votre consommation via les journaux,
- répartir vos appels sur la journée si possible.
Alternatives intelligentes : webhooks, cache, HubDB
Pour réduire la pression sur les APIs :
- Utilisez des webhooks : avec les workflows HubSpot, vous pouvez envoyer des données automatiquement sans passer par une fonction serverless.
- Stockez les données dans HubDB : un cache temporaire côté CMS, utile pour éviter des appels répétés à une même API externe.
- Générez des fichiers statiques si possible : pour des données rarement mises à jour, un contenu généré à l’avance évite tout appel dynamique.
Ces options vous permettent de garder vos appels API ciblés, efficaces et toujours dans les limites autorisées.
Limites techniques des serverless functions HubSpot
Limites de performance et d’exécution
Les fonctions serverless sur HubSpot sont pensées pour des traitements rapides et légers. Cela se traduit par des contraintes strictes :
- Durée maximale d'exécution : 10 secondes par fonction
- Mémoire allouée : 128 Mo
- Charge utile maximale : 6 Mo par appel
- Temps d’exécution total : 600 secondes par minute (partagé entre toutes les fonctions du compte)
Au-delà de ces seuils, la fonction échoue et retourne une erreur 429. Cela peut poser problème pour des appels complexes ou des traitements lourds.
Pas de support des imports/dépendances multiples
Les fonctions serverless HubSpot ne permettent pas d’importer plusieurs fichiers JavaScript. Tout le code doit être contenu dans un seul fichier. Cela limite :
- la structuration modulaire du code,
- l’usage de librairies tierces volumineuses (sauf via Webpack dans les projets développeur),
- la réutilisabilité des fonctions entre projets.
Résultat : votre code peut vite devenir long et difficile à maintenir s’il n’est pas rigoureusement organisé.
Debugging pas toujours évident
Le débogage côté HubSpot n'est pas aussi fluide qu’un environnement local :
- Les logs sont disponibles, mais en lecture différée.
- Pas de console directe : vous devez passer par l’interface ou la CLI pour lire les traces.
- Les erreurs ne renvoient pas toujours de détails explicites, surtout si le problème survient côté HubSpot (quotas, secrets invalides etc.).
Astuce : utilisez console.log() de manière ciblée et systématique dans vos fonctions pour faciliter l’analyse.
Quand utiliser les serverless functions (et quand éviter)
À privilégier si :
- Vous avez besoin de sécuriser un appel API sans exposer de données sensibles côté client (ex. : clé d'API tierce).
- Vous voulez interagir avec le CRM ou HubDB directement depuis un formulaire CMS ou une page dynamique.
- Votre cas d’usage est simple et rapide : transformation de données, validation, enrichissement léger etc.
- Vous souhaitez éviter un serveur externe : les fonctions sont hébergées par HubSpot, vous n’avez rien à maintenir.
- Votre fonction est appelée à la volée (ex. au clic sur un bouton) sans impact massif sur les performances globales du site.
À éviter si :
- Votre traitement dépasse 10 secondes ou nécessite des appels multiples en chaîne.
- Vous avez besoin de gérer de gros volumes de données ou d'importer plusieurs modules complexes.
- Vous ne pouvez pas stocker localement les secrets de manière sécurisée (ex. hors projet développeur).
- Vous avez besoin d’une vraie logique métier back-end avec plusieurs routes, persistance avancée ou files d’attente.
- Votre application dépend de librairies spécifiques difficiles à packager dans un seul fichier .js.
Dans ces cas, une API intermédiaire hébergée en externe (via un serveur Node.js, un backend Firebase, ou AWS Lambda) sera souvent plus adaptée.
Nos conseils pour des fonctions serverless performantes et durables
- Commencez petit et testez souvent : une fonction = un objectif clair. Évitez les logiques tentaculaires difficiles à maintenir.
- Limitez la charge côté HubSpot : si une donnée peut être mise en cache, faites-le. Moins d’appels = plus de fiabilité.
- Surveillez vos logs régulièrement : HubSpot propose des journaux détaillés, ne les ignorez pas. Ils sont cruciaux pour détecter les erreurs silencieuses.
- Centralisez la gestion des secrets : utilisez les secrets pour sécuriser vos tokens. Ne jamais hardcoder une clé directement dans le code.
- Respectez les quotas API : regroupez les appels, utilisez les endpoints de batch si disponibles, évitez les appels superflus.
- Préparez un fallback : en cas d’échec, prévoyez un plan B (affichage de message, données statiques etc.).
- Anticipez l’évolution : les besoins changent. Pensez “modulaire” dès le départ pour faciliter les itérations.
Avec ces bonnes pratiques, vos fonctions serverless ne seront pas juste “déployées”, elles seront fiables, scalables et vraiment utiles.
Besoin d’aide ? Faites appel à une Agence Hubspot experte !
