API et webhooks : la base à comprendre quand on pilote un CRM

Vous pilotez un projet CRM et votre intégrateur vous parle de rate limits, d’idempotency et de webhooks comme si c’était du français. Vous demandez combien ça va coûter en tâches Zapier, il répond « dépend de l’API ». Vous sentez qu’on vous cache quelque chose. C’est normal. Vous devez comprendre les API et webhooks — pas pour coder, mais pour piloter vos intégrations sans vous faire bluffer.

Pourquoi un chef de projet doit comprendre les API (sans coder)

Une API, c’est le contrat entre deux applications pour qu’elles se parlent. Votre CRM à une application d’enrichissement de données, c’est une API. Vos formulaires web qui créent des leads en HubSpot, c’est une API. Zapier qui lance vos workflows, c’est une API.

Pourquoi comprendre ? Parce que sans ça, vous acceptez les délais qu’on vous propose, les coûts en tâches, les dérapes d’intégration. Vous découvrez trop tard qu’une intégration qui « devrait coûter 30 €/mois » en coûte 300 € parce que l’API rate-limite vos appels. Ou qu’une synchronisation multi-CRM tombe tous les jeudis à 14 h sans raison. Ou que personne n’a pensé à rendre l’automation idempotente, donc vous créez des doublons contacts.

Ce chapitre n’est pas de la théorie. C’est du pragmatisme : les trois concepts clés qui vont changer votre rapport aux intégrateurs.

Une API, c’est quoi ? L’analogie du serveur de restaurant

Imaginez un restaurant. Vous êtes client dehors, le serveur est l’API. Voici ce qui se passe :

Vous (application client) appelez le serveur (API) avec une demande : « Je veux un steak frites. » Le serveur répond : « Pas de problème, voici le menu (documentation API), le steak frites coûte 25 € (pricing), je reviens en 15 minutes (latence) ». Pendant ce temps, le serveur transmet votre commande à la cuisine (serveur backend). La cuisine prépare votre plat, le serveur revient avec le résultat : « Voici votre assiette. »

Si vous appelez le serveur 100 fois en 1 minute pour la même commande, il va vous dire « whoa, tu vas trop vite, attends 1 minute » (rate limiting). Si vous n’indiquez pas votre numéro de table (authentification), il vous demande de vous identifier avant d’écrire votre commande. Si vous changez d’avis et annulez après que la cuisine ait commencé, c’est compliqué (idempotency : comment annuler sans créer du bazar).

HubSpot API = le serveur. Zapier = vous (le client qui appelle). Les rate limits = le serveur dit « pas plus de 10 appels par seconde ». Les webhooks = au lieu que vous demandiez « as-tu du nouveau ? » toutes les minutes, le restaurant appelle VOUS quand c’est prêt. Ça économise 99 % des appels inutiles.

REST, GraphQL, SOAP : ce qu’il faut retenir en 2026

Il y a trois styles d’API : REST, GraphQL, SOAP. Vous rencontrerez surtout REST.

REST : le standard depuis 2008. Vous appelez des URLs comme https://api.hubspot.com/crm/v3/contacts, vous pouvez dire GET (demander info), POST (créer), PUT (modifier), DELETE (supprimer). C’est intuitif. HubSpot, Salesforce, Pipedrive utilisent REST. Make et Zapier trouvent ça facile à intégrer.

Limitation de REST : si vous voulez les données du contact ET ses notes ET ses deals, vous faites 3 appels REST séparé. À grande échelle (1000 contacts), c’est 3000 appels = lourd. Et cher : chaque appel compte.

GraphQL : le trendy depuis 2016. Vous dites exactement quels champs vous voulez, et l’API renvoie juste ça. Une requête GraphQL = une réponse optimale. Exemple : vous récupérez contact + notes + deals en un appel au lieu de trois. Moins d’appels = moins cher en tâches Zapier/Make. Shopify utilise GraphQL, c’est devenu courant en e-commerce.

Limitation : GraphQL est plus strict syntaxiquement. Zapier et Make doivent supporter (oui, ils le font). Mais moins d’intégrateurs graphQL pré-construites qu’en REST.

SOAP : l’ancêtre années 2000, encore utilisé par Salesforce « legacy » et quelques banques. XML verbeux, lourd, dépassé. Salesforce propose REST maintenant, mais si votre intégrateur dit « il faut SOAP », dites-lui « pourquoi pas REST ? ».

En 2026, le choix : vous utilisez l’intégration Zapier/Make pré-construite (elle choisit REST ou GraphQL pour vous), ou vous faites des appels API manuels (vous devez comprendre le style). Si vous ne faites que créer/modifier/supprimer des contacts, REST suffit. Si vous faites de la synchronisation bidirectionnelle complexe, GraphQL économise.

Authentification : clé API, OAuth, JWT — l’essentiel

L’API doit vous reconnaître. Trois méthodes :

Clé API : la plus simple. Vous avez une clé, genre « sk_test_abc123xyz ». À chaque appel, vous passez la clé : « Bonjour, c’est moi (clé = abc123xyz), je veux créer un contact. » Avantage : simple, direct. Inconvénient : si la clé fuit, n’importe qui crée des contacts sous votre nom. HubSpot, Pipedrive utilisent ça.

OAuth : l’approche sécurisée 2.0. Vous dites à votre application « OK je te donnes le droit de créer/lire mes contacts, mais seulement ceux-là, seulement pendant 30 jours ». En arrière-plan, Salesforce ou HubSpot vous donne un « token » limité en durée et permissions. Avantage : granulaire, révocable. Inconvénient : d’abord authentifier l’utilisateur, puis accorder les droits. Zapier demande souvent OAuth (c’est plus sûr).

JWT : (JSON Web Token) style hybride. Un jeton signé qui dit « c’est Alice, elle a les droits contact + deal, valide jusqu’à demain ». Plus technique qu’une clé, moins lourd qu’OAuth complet. Utile quand vous avez des intégrations serveur-serveur.

En pratique : Zapier vous demandera « connecte-toi à HubSpot » (OAuth), Zapier reçoit un token limité, vous dormez bien. Si vous écrivez du code Python custom, vous utiliserez une clé API (mais stockée en secret, pas en dur dans le code).

Methode	Complexité	Sécurité	Révocation	Qui l’utilise
Clé API	Très simple	Moyenne	Manuelle	HubSpot, Pipedrive, Brevo
OAuth 2.0	Modérée	Haute	Automatique (expiration)	Salesforce, Google, Facebook
JWT	Modérée	Haute	Automatique	API avancées, SaaS B2B

Rate limits : pourquoi vos workflows tombent à 14 h pile

Un rate limit, c’est : « tu peux faire max 10 appels par seconde, pas plus ». C’est le garde du restaurant qui dit « une commande à la fois, attends ton tour ».

Pourquoi ? Parce que si 1000 clients Zapier font chacun 100 appels/seconde à HubSpot, les serveurs HubSpot explosent. Donc HubSpot dit « Pro : max 100 appels/seconde, Enterprise : 1000/sec ». Zapier respecte ça (sinon HubSpot l’expulse). Si vous dépassez, HubSpot répondra « 429 Too Many Requests, réessaie dans 60 secondes ».

Conséquemment : si vous lancez 100 workflows Zapier qui chacun font 5 appels HubSpot et que vous les déclenchez tous en même temps (ex: 14 h quand une campagne marketing se termine), brusquement 500 appels arrivent sur HubSpot à la seconde. Rate limit atteint, workflows hang, vous criez « ça marche pas ».

Réalité 2026 : HubSpot Pro = 5 appels/sec par clé API. Enterprise = 100/sec. Salesforce API = 15 appels/sec. Si vous pilotez 20 intégrations Zapier dans HubSpot Pro, prévoyez un délai ou risquez les 429.

Bonne pratique : demandez à votre intégrateur « quel est le rate limit de l’API que tu appelles ? combien d’appels par seconde tu vas faire ? est-ce qu’il y a une queue ou un délai ? » Si la réponse est « on verra bien », fuyez.

Webhooks : l’inverse des API, et pourquoi c’est puissant

Une API classique : vous appelez, vous attendez, vous recevez une réponse. Ça marche si vous savez quand faire l’appel.

Un webhook : HubSpot vous dit « quand tu crées un contact, envoie-moi un signal (webhook) pour que j’agisse ». Au lieu que Zapier demande 1000 fois par jour « y a-t-il du nouveau ? », HubSpot appelle Zapier quand c’est vraiment nouveau. Une sonnette au lieu de frapper à la porte toutes les 30 secondes.

Avantages du webhook : (1) presque gratuit en volume (pas de tâches Zapier qui explosent), (2) temps réel (dès que c’est créé), (3) pas de lag de polling.

Inconvénients : (1) vous devez avoir une URL pour recevoir le webhook (Zapier crée ça pour vous), (2) le webhook peut échouer (network error) et vous devez avoir un retry, (3) plus fragile que du polling classique.

Exemple : Un contact est créé dans HubSpot. Via API polling (Zapier check toutes les minutes) : 1440 appels API par jour, même si 0 contact est créé. Via webhook : HubSpot appelle Zapier une fois, zéro appels inutiles. À 100 appels/sec limit, c’est énorme.

Réalité : la plupart des CRM modernes supportent les webhooks. HubSpot oui, Salesforce oui (Platform Events, meilleur que webhooks), Pipedrive oui. Si votre partenaire dit « qu’on doit poller », demandez-lui pourquoi, souvent c’est de la paresse.

Idempotency : comment ne pas créer de doublons

Voici le scénario : un webhook arrive, crée un contact, mais le réseau explose avant qu’HubSpot confirme le succès. Zapier pense « oh, ça a échoué », réessaie, crée un deuxième contact identique. Bam, doublon. Désastre.

L’idempotency dit : « si tu envoies deux fois la même action, le résultat doit être un seul objet, pas deux ». Comment ? En utilisant une clé unique. Exemple : « crée un contact avec email = jean@example.com. Si un contact avec cet email existe déjà, mets-le à jour au lieu de le créer ».

Problème : ça demande que l’API supporte l’upsert (update-or-insert). HubSpot supporte (by email), Salesforce supporte (by external ID), Pipedrive moins (faut faire une recherche avant). Zapier doit gérer ça ou vous avez des doublons.

Bon test : demandez à votre intégrateur « tu as pensé à l’idempotency ? comment tu gères les retries ? tu vas créer des doublons ? » Si la réponse est « on verra en prod », vous avez un problème.

Comment lire une documentation API en 5 minutes

La doc d’une API c’est souvent : endpoints, méthodes (GET/POST/PUT/DELETE), authentification, rate limits, exemples.

Checklist rapide : (1) Authentification : clé API ou OAuth ? (2) Rate limits : combien d’appels/sec ? (3) Webhook support : oui ou non ? (4) Retry/idempotency : géré comment ? (5) Latence SLA : combien de temps avant réponse ? (6) Exemples de code : au moins un exemple JSON.

Si la doc répond à ces 6 points, c’est une API « productioon-ready ». Si ça répond à 3-4, préparez-vous aux surprises.

Les 7 questions à poser à votre intégrateur sur les API

Avant de signer, posez ces 7 questions :

1. Combien d’appels API vont être faits par jour/mois ? Si c’est « on sait pas », c’est mauvais signe. Une bonne estimation : « 10 000 leads/mois × 3 appels par lead (créer, enrichir, router) = 30 000 appels/mois = 1000/jour ». C’est du dimensionning basique.

2. Est-ce du polling ou du webhook ? Webhook c’est mieux. Polling avec un jitter (décalage aléatoire entre workers) pour ne pas faire un spike à 14h, c’est OK.

3. Quel rate limit va-t-on utiliser de l’API ? Si vous avez HubSpot Pro (5 req/sec), que vous avez 20 intégrations Zapier qui chacun font 1 req/sec en simultané = dépassement garanti. Vous devez un plan : queue, délai, ou upgrade HubSpot.

4. Avez-vous pensé à l’idempotency et aux retries ? La réponse doit être oui + une explication. Sinon, doublons garantis.

5. Quelle est la latence acceptable (combien de secondes entre l’événement et l’action) ? Temps réel = webhook. 5 min = OK. 1h = polling. Ça change le design.

6. Qu’est-ce que vous allez faire si l’API tombe pendant 2h ? Des événements vont être perdus (webhook) ou ratés (polling). Y a-t-il un plan de rattrapage ? Un audit pédodique ? Ou on croise les doigts ?

7. Quel est le coût réel en tâches Zapier/Make, pas une estimation ? Faites-le calculer sur un mois réel. Pas « environ 30 € », mais « 47 € basé sur 15 000 tâches réelles ».

Vous voulez parler de votre projet ? Contactez Cloud Koala, on revient vers vous sous 24 h.

Pour aller plus loin

Si cet article vous a été utile, ces lectures complémentaires de notre blog le prolongent bien :

Questions fréquentes

Si une API tombe, est-ce qu’on perd les événements ?

Oui, sauf si vous avez une queue (file d’attente). Webhook sans retry = perdu. Polling = raté jusqu’au prochain poll. Bonne pratique : une Dead Letter Queue qui log les erreurs, audit hebdo, alert sur les erreurs critiques. Sinon, contact perdu = lead perdu.

Peut-on faire une intégration sans API (juste import/export CSV) ?

Oui, mais c’est du 1999. Vous téléchargez un CSV tous les jours, vous l’uploader dans CRM. Latence énorme (data d’hier), risque de doublon élevé. Ça marche pour des PME très petites (5-10 leads/jour). Au-delà, c’est ingérable.

JWT, ça change quoi pour un chef de projet ?

Presque rien. C’est entre l’intégrateur et l’API. Juste sachez que c’est plus sécurisé que clé API, moins complexe qu’OAuth full. Si votre intégrateur dit « on va utiliser JWT », c’est bon signe (il pense sécurité).

Zalier, Make, n8n gérent toutes les authentifications ?

Presque. Zapier et Make : 99 % des CRM connus. n8n : 80 % (moins d’intégrations pré-construites, mais vous pouvez faire du custom). Si l’API est « obscure », l’intégrateur code custom (coût supplémentaire, risque plus haut).

Combien coûte un appel API mal conçu en tâches Zapier ?

Vite cher. Un appel HTTP = 1 tâche. Lookup échoué = 1 tâche. Retry = 1 tâche. Une « simple » synchro qui crée contact + note + deal = 3 appels × nb leads = 3 × 5000 = 15 000 tâches/mois. À 29 € pour 2000, ça devient 220 €. Mal conçu (avec lookups inutiles) ça peut être 500 €. Plan d’API : 10 €. Différence : 200 €/mois.

Comment on sait si le rate limit est un problème avant de lancer ?

Stress test : vous lancez l’intégration en test sur un sous-ensemble (100 leads au lieu de 5000). Vous observez les logs. Si vous voyez des 429 (Too Many Requests), le rate limit est un problème. Sinon, ça scale. Pas de test = surprise en prod.