API HubSpot : REST, GraphQL, OAuth & webhooks
API HubSpot : REST et GraphQL, authentification OAuth vs Private Apps, webhooks, rate limits et architecture. Le guide pour connecter et étendre HubSpot par le code.
L'API HubSpot permet de connecter HubSpot à vos outils et d'y construire des applications sur-mesure par programmation. Elle expose des endpoints REST (et GraphQL pour les requêtes complexes), s'authentifie via OAuth 2.0 ou des Private Apps (les clés API sont dépréciées depuis 2022), pousse des événements en temps réel via webhooks, et impose des limites de débit selon votre abonnement. C'est la brique technique qui transforme HubSpot en hub de données de votre système d'information.
Trois usages principaux
- Synchroniser : faire dialoguer HubSpot avec un ERP, un outil de facturation, un produit SaaS.
- Étendre : créer des Custom Objects, des propriétés, des cartes CRM custom (UI Extensions).
- Construire : développer des applications métier (portails, générateurs de documents) avec HubSpot en back-end → Applicatifs métiers.
REST ou GraphQL ?
REST reste l'interface principale (endpoints par objet : /crm/v3/objects/contacts, companies, deals, tickets…). GraphQL est utile pour les requêtes complexes qui nécessiteraient sinon plusieurs appels REST — on récupère exactement les champs voulus en une requête.
Plusieurs versions cohabitent (v1, v2, v3) : certains endpoints n'existent qu'en v1, d'autres qu'en v3. À cadrer en amont.
OAuth, Private App… mais pas de clé API
| Méthode | Usage | Distribuable ? |
|---|---|---|
| OAuth 2.0 | Apps multi-comptes / marketplace | Oui |
| Private App (token d'accès) | Intégration interne à un seul portail | Non |
| Clé API | Dépréciée depuis 2022 | — |
Prérequis : un compte développeur (distinct du compte HubSpot standard), l'enregistrement d'une app (Client ID + Client Secret). Régénérer le Client Secret casse toutes les intégrations existantes — à protéger.
Temps réel et économie d'appels
Les webhooks permettent à HubSpot de pousser un événement (création de contact, modification de propriété, suppression) vers votre application dès qu'il se produit — au lieu d'interroger l'API en boucle (polling). Disponibles sur tous les tiers, jusqu'à 1 000 abonnements par app.
Passer du polling aux webhooks réduit drastiquement le volume d'appels.
Concevoir pour les limites, pas contre elles
HubSpot impose deux types de limites :
- Burst (par 10 s, par app) : ~100 requêtes (Free/Starter), ~190 (Pro/Enterprise).
- Quota journalier (partagé par compte) : de ~100 000 à ~1 000 000 selon le tier ; add-on « API Limit Increase » (+1M, jusqu'à +2M).
La Search API a une limite à part (~4 req/s) et peut renvoyer des données légèrement obsolètes.
Bonnes pratiques de production : un 429 signale un dépassement. On conçoit donc dès le départ : batching (jusqu'à 100 enregistrements/appel), retries avec back-off, file d'attente (queue), cache, et surveillance via le header X-HubSpot-RateLimit-Daily-Remaining.
Ce qu'on construit avec l'API
- Synchronisation bidirectionnelle ERP ↔ HubSpot
- Création/alimentation de Custom Objects depuis un outil métier
- Portail client (Next.js) branché sur les données HubSpot
- Génération de documents déclenchée par un événement
- Remontée d'usage produit (SaaS) dans le CRM
Choisir la bonne méthode de connexion
| Méthode | Quand |
|---|---|
| Intégration native (marketplace) | Le connecteur existe et couvre le besoin |
| No-code (Make / N8N) | Flux standards, fiables, sans besoin de robustesse extrême |
| API sur-mesure | Logique métier complexe, volume élevé, robustesse et contrôle requis |
Pas de dogme : on choisit selon la robustesse et le coût. Le développement API se justifie quand le métier l'exige.
Questions fréquentes sur l'API HubSpot
À quoi sert l'API HubSpot ?
L'API HubSpot permet de connecter HubSpot à vos outils (ERP, facturation, produit SaaS) et de construire des applications métier sur-mesure par programmation, en lisant et écrivant des données dans le CRM.
Quelle authentification utiliser ?
OAuth 2.0 pour les apps distribuées (marketplace, multi-comptes). Private App (token d'accès) pour les intégrations internes à un seul portail. Les clés API sont dépréciées depuis 2022.
Quelles sont les limites de l'API ?
Environ 100-190 requêtes par 10 secondes (burst, selon l'abonnement) et un quota journalier de 100 000 à 1 000 000 requêtes. La Search API est limitée à ~4 requêtes par seconde.
API, no-code ou intégration native ?
L'intégration native quand le connecteur existe, le no-code (Make/N8N) pour les flux standards, l'API sur-mesure quand la logique métier ou le volume l'exige. On choisit selon la robustesse et le coût.
---
Besoin de construire vos intégrations API HubSpot ?
Découvrir notre offre Applicatifs métiers → · Diagnostic gratuit