Webhooks

L'interrogation d'API (API polling) implique que le système récepteur demande de manière répétée au système source « y a-t-il eu des changements ? » à des intervalles fixes (toutes les 1 minute, toutes les 5 minutes). C'est inefficace : la plupart des requêtes d'interrogation renvoient « aucun changement », consommant le quota d'API et créant de la latence (la latence maximale est égale à l'intervalle d'interrogation). Les webhooks inversent ce modèle : le système source notifie le récepteur dès qu'un événement se produit, atteignant une latence quasi nulle sans appels d'API gaspillés. La limitation est la fiabilité : les webhooks sont « fire and forget » (tirer et oublier) par défaut — si le système récepteur est hors service, les événements sont perdus. Les systèmes de webhooks bien conçus ajoutent une logique de nouvelle tentative avec un backoff exponentiel (tentatives de livraison multiples sur des intervalles croissants) et des journaux de livraison (visibles dans l'interface utilisateur du produit afin que les clients puissent vérifier si leur endpoint a reçu chaque événement et enquêter sur les échecs).

Les échecs de webhooks comptent parmi les tickets de support d'intégration les plus complexes car ils concernent les deux côtés de l'intégration. Scénarios courants : (1) L'endpoint ne reçoit pas les événements — vérifiez que l'URL de l'endpoint est accessible publiquement (pas localhost), que le serveur a accepté l'événement de test et que le type d'événement est souscrit. (2) La réponse HTTP 200 n'est pas renvoyée — le serveur récepteur doit renvoyer un statut HTTP 200 dans la fenêtre de timeout (généralement 10 à 30 secondes) ; si cela prend plus de temps, la plateforme de webhook marque la livraison comme échouée même si le serveur a finalement traité l'événement. (3) Événements en double — les consommateurs de webhooks bien conçus doivent être idempotents (le traitement du même événement deux fois produit le même résultat que le traitement une seule fois) en utilisant l'ID unique de l'événement pour détecter et ignorer les doublons. (4) Échec de la vérification de la signature — la plupart des API SaaS signent les payloads de webhook avec HMAC-SHA256 en utilisant une clé secrète ; le code du client doit vérifier cette signature sur chaque événement reçu pour prévenir les attaques de webhooks falsifiés.

Les Product Ops collaborent avec l'Ingénierie pour concevoir des capacités de webhook qui minimisent la charge de support et maximisent la satisfaction des développeurs. Bonnes pratiques : couverture des types d'événements (chaque changement d'état significatif dans le produit devrait avoir un événement webhook correspondant) ; conception du payload d'événement (les payloads devraient inclure toutes les données nécessaires pour agir sur l'événement sans un appel d'API de suivi — inclure l'état complet de l'objet, pas seulement des ID qui nécessitent une requête GET ultérieure) ; interface utilisateur des journaux de livraison (un journal d'événements consultable dans le tableau de bord du produit où les développeurs peuvent voir chaque événement déclenché, son statut de livraison, la réponse HTTP du serveur, et un bouton « redeliver » pour une nouvelle tentative manuelle) ; vérification de la signature (signer chaque payload avec HMAC-SHA256 et documenter clairement le processus de vérification) ; et payloads versionnés (lorsque le schéma d'événement doit changer, versionner le payload et prendre en charge les deux versions simultanément pendant une période de transition — ne jamais apporter de modifications incompatibles à un payload de webhook sans préavis).