Webhook vs API expliqué avec un tableau comparatif, les compromis entre polling et push, un vérificateur de signature HMAC dans le navigateur, la gestion des relances et un code de réception idempotent.
Avec un appel d'API, votre code demande des données à un autre service quand il le souhaite : c'est le pull. Avec un webhook, le service envoie une requête HTTP POST à votre URL dès que quelque chose se produit : c'est le push. La plupart des intégrations utilisent les deux, un webhook pour apprendre rapidement un changement et un appel d'API pour récupérer l'enregistrement complet et à jour.
Requête d'API vs webhook
Interroger une API chaque minute pour savoir si un paiement est passé gaspille des requêtes et arrive quand même en retard. Un webhook inverse le sens, mais il vous transfère aussi la responsabilité : votre endpoint doit être public, prouver que chaque message est authentique, répondre vite et supporter qu'un même événement arrive deux fois. Cette page traite chacune de ces tâches avec du code à copier.
Grosso modo, oui. C'est une requête HTTP avec un corps JSON, simplement envoyée dans le sens inverse. On parle parfois d'API inversée. La différence qui compte, c'est qui lance l'échange et qui doit être en ligne pour le recevoir.
Utilisez des webhooks quand le fournisseur en propose pour les événements dont vous avez besoin et que vous pouvez héberger un endpoint HTTPS public. Faites du polling quand il n'y a pas de webhook, quand vous êtes derrière un pare-feu, ou pour un petit nombre de vérifications où une minute de délai ne pose pas de problème.
La plupart des fournisseurs envoient dans un en-tête un HMAC SHA-256 du corps, calculé avec un secret que vous êtes seuls, eux et vous, à connaître. GitHub, par exemple, utilise X-Hub-Signature-256 avec un préfixe sha256= ; Stripe utilise Stripe-Signature avec un horodatage. Recalculez-le et comparez avant de faire confiance à quoi que ce soit.
La plupart des fournisseurs relancent les livraisons échouées avec des intervalles croissants entre les tentatives, pendant une durée qui dépend du fournisseur. Stripe, par exemple, continue de relancer les événements live pendant jusqu'à trois jours. Ensuite, l'événement n'est disponible que via son API ou son tableau de bord.
Les fournisseurs n'attendent une réponse que peu de temps. Si votre code envoie d'abord des e-mails ou appelle d'autres services, la livraison peut expirer et être relancée, alors que vous avez déjà agi. Mettez la tâche en file d'attente, renvoyez 200, et traitez ensuite.
express.raw conserve le corps sous forme d'octets pour que la signature corresponde. Ce format d'en-tête suit la convention sha256= de GitHub ; adaptez le nom de l'en-tête pour les autres fournisseurs.
Un index unique sur l'identifiant d'événement fait échouer l'insertion lors d'une seconde livraison, le travail ne s'exécute donc qu'une fois, quel que soit le nombre d'arrivées de l'événement.
ON CONFLICT DO NOTHING ne renvoie aucune ligne pour un doublon, que votre code traite comme déjà géré.
Le polling est plus simple à héberger mais plus lent et plus bavard. Gardez un curseur pour que chaque interrogation ne demande que ce qui est nouveau.
Collez un corps et un secret pour calculer la signature qu'un fournisseur enverrait, puis collez l'en-tête reçu pour comparer. Tout s'exécute dans votre navigateur avec la Web Crypto API ; rien n'est envoyé nulle part.
Corps brut de la requête
Secret du webhook
Signature que ce corps devrait porter
En-tête de signature reçu (facultatif)
Correspondance : le corps et le secret produisent cette signature.
Aucune correspondance : soit le corps a changé, soit le secret est faux, soit l'en-tête utilise un autre format.
Calcul en cours
Commencer gratuitement · Sans carte bancaire