« Faut-il passer par l’API ou par un webhook ? » La question revient dans presque tous les projets d’intégration. Réponse courte : ils ne sont pas concurrents. Une API permet à votre système de demander des données à un autre système ou de lui faire exécuter une action. Un webhook permet à l’autre système de prévenir le vôtre qu’un événement vient de se produire. Les intégrations fiables utilisent en général les deux.
La différence en une phrase chacun
- API (on va chercher) : votre serveur envoie une requête quand il le décide (« donne-moi les commandes modifiées depuis 10 h », « crée ce client ») et reçoit une réponse.
- Webhook (on vous prévient) : l’autre plateforme envoie une requête HTTP vers une adresse que vous avez enregistrée dès qu’un événement se produit (« une commande a été payée », « un remboursement a été créé »).
Webhook ou API : le comparatif
| API | Webhook | |
|---|---|---|
| Qui lance l’échange | Votre système | L’autre plateforme |
| Quand arrivent les données | Quand vous les demandez (à la demande ou à intervalle fixe) | Peu après l’événement |
| Sens | Lecture et écriture | Notification seulement (l’API reste nécessaire pour agir) |
| Usage typique | Créer ou modifier des données, rechercher, rattraper après une panne | Réagir à un événement : paiement confirmé, commande créée, stock modifié |
| Risque principal | Interroger trop souvent (limites d’appels) ou trop rarement (données périmées) | Livraisons manquées, retardées, en double ou falsifiées |
| Ce qu’il faut construire | Authentification, pagination, gestion des limites | Une adresse HTTPS publique, la vérification de signature, la gestion des doublons |
Un exemple e-commerce : une commande payée qui arrive dans votre logiciel comptable
Vous voulez que chaque commande Shopify payée apparaisse dans votre logiciel de comptabilité.
- Le webhook annonce l’événement. Shopify envoie un webhook de commande vers votre adresse dès que la commande est créée ou mise à jour.
- Votre service répond vite. Il vérifie la signature, enregistre l’événement et renvoie immédiatement un statut 2xx. Le traitement lourd se fait ensuite, en arrière-plan.
- L’API fait le travail. Votre service lit si besoin la commande complète via l’API Admin de Shopify, puis appelle l’API du logiciel comptable pour créer la vente ou la facture.
- Une vérification planifiée comble les trous. Une fois par heure ou par jour, votre service interroge l’API Shopify sur les commandes récentes et complète ce qu’un webhook aurait pu manquer.
Le webhook apporte la rapidité ; l’API apporte le contrôle et la capacité de rattrapage. C’est en s’appuyant sur un seul des deux que la plupart des intégrations se cassent.
Webhooks : les points à maîtriser
Vérifier chaque livraison
N’importe qui peut envoyer une requête à une adresse publique. Shopify signe ses livraisons avec un HMAC calculé à partir du corps brut de la requête et du secret de l’application : votre service doit le recalculer et rejeter toute requête dont la signature ne correspond pas.
Répondre vite, traiter ensuite
Les plateformes attendent une réponse 2xx rapide. La documentation de Shopify indique par exemple que les livraisons de webhooks de commande en échec sont relancées jusqu’à 8 fois sur 4 heures, avec un délai croissant, et recommande d’accuser réception rapidement puis de traiter le reste hors de la requête.
Prévoir les doublons et le désordre
Une relance peut livrer deux fois le même événement, et deux événements peuvent arriver dans un ordre différent de celui où ils se sont produits. Enregistrez un identifiant par événement traité et rendez le traitement idempotent : traiter deux fois le même événement ne doit pas créer deux factures.
Ne jamais compter uniquement sur les webhooks
Un serveur tombe, un déploiement a lieu, un certificat expire. C’est la réconciliation périodique par l’API qui rend une intégration digne de confiance.
API : les points à maîtriser
Respecter les limites d’appels
Chaque API limite le volume de requêtes. L’API Admin GraphQL de Shopify, par exemple, calcule un coût par requête avec une réserve qui se recharge en continu, selon le forfait de la boutique. Ne demandez que les champs utiles et ralentissez quand l’API vous freine.
Garder les identifiants côté serveur
Les clés d’API et jetons d’accès doivent rester sur un serveur, jamais dans le JavaScript public du site ou dans le thème. Ne demandez que les autorisations nécessaires à l’intégration.
Anticiper les évolutions
Les API sont versionnées. Fixez la version utilisée, suivez les annonces d’obsolescence et testez avant de changer de version.
Lequel choisir ?
- Vous devez réagir en quelques secondes à un événement (paiement confirmé, commande créée) : webhook, puis l’API pour agir.
- Vous devez créer ou modifier des données dans un autre système : API.
- Vous avez besoin d’un export nocturne ou d’un rapport : API planifiée.
- L’autre plateforme ne propose pas de webhooks : interrogation de l’API à un intervalle raisonnable.
- De l’argent ou du stock est en jeu : les deux, avec réconciliation.
Questions fréquentes
Un webhook est-il une sorte d’API ?
On le décrit souvent comme une « API inversée » : mêmes briques (HTTP, JSON), mais l’appel va dans l’autre sens. En pratique, l’API classique de la plateforme reste nécessaire pour lire les détails ou faire des modifications.
Interroger une API régulièrement est-il une mauvaise pratique ?
Non, si l’intervalle est raisonnable et respecte les limites d’appels. C’est le bon outil pour rattraper des données et pour les plateformes sans webhooks ; ce n’est pas le bon outil pour réagir quasiment en temps réel.
Vous reliez Shopify, un prestataire de paiement et vos outils métier ? Voir nos services d’intégration API et nos intégrations Shopify, ou décrivez votre projet.