Skip to main content
AccueilBlogGuidesQue doit renvoyer un point de terminaison de webhook de suivi ? Codes d’état, délais d’expiration et nouvelles tentatives ?

Que doit renvoyer un point de terminaison de webhook de suivi ? Codes d’état, délais d’expiration et nouvelles tentatives ?

17TRACK

Un point de terminaison de webhook de suivi doit renvoyer une réponse 2xx rapide et intentionnelle après avoir accepté l’événement pour traitement. Dans la plupart des intégrations, le schéma le plus sûr consiste à authentifier la requête, à valider la charge utile, à stocker ou mettre l’événement en file d’attente, puis à l’accuser réception avec 200 OK ou 202 Accepted. Utilisez des réponses 4xx pour les requêtes que l’expéditeur ne doit pas réessayer, et des réponses 5xx lorsqu’un problème temporaire côté serveur a empêché l’acceptation. Le comportement exact en matière de délai d’expiration et de nouvelle tentative dépend toujours du contrat du fournisseur de webhook ; votre implémentation doit donc être conçue en fonction du comportement documenté de l’expéditeur plutôt que de suppositions.

Quels codes d’état et délais d’expiration un point de terminaison de webhook de suivi doit-il renvoyer

Pour un webhook de suivi ou d’état d’expédition, cette distinction est importante, car les événements de livraison peuvent arriver plusieurs fois, dans le désordre ou être rejoués après une défaillance réseau. Le rôle du point de terminaison n’est pas nécessairement de terminer chaque opération métier avant de répondre. Sa première fonction est de déterminer de manière fiable si l’événement a été accepté.

Le contrat de réponse en pratique

Une réponse de webhook s’adresse à deux destinataires : le système expéditeur et votre propre application. L’expéditeur a besoin d’un résultat HTTP clair pour décider s’il doit marquer la livraison comme réussie, la réessayer ou l’arrêter. Votre application a besoin de suffisamment de temps pour vérifier et enregistrer durablement l’événement. Ces objectifs sont plus faciles à atteindre lorsque le point de terminaison dispose d’un chemin synchrone court et d’un chemin de traitement asynchrone distinct.

  1. Recevoir la requête HTTP via HTTPS.
  2. Vérifier la signature, les identifiants d’authentification, l’horodatage ou les autres contrôles d’intégrité de la requête requis par le fournisseur.
  3. Analyser et valider la charge utile sans effectuer de traitement lent en aval.
  4. Écrire l’événement, ou un enregistrement de déduplication et une référence d’événement, dans un stockage durable ou une file d’attente fiable.
  5. Renvoyer une réponse 2xx intentionnelle.
  6. Traiter de manière asynchrone la mise à jour du suivi, la notification client, la modification des stocks ou toute autre action métier.

Une réponse ne doit pas déclarer l’acceptation si l’événement existe uniquement dans la mémoire du processus. Si l’application tombe immédiatement après avoir renvoyé le succès, un événement qui n’a jamais été conservé peut être perdu alors que l’expéditeur croit que la livraison a réussi. Le moment où vous renvoyez une réponse 2xx doit donc correspondre à votre garantie réelle de durabilité.

Quel code d’état un webhook doit-il renvoyer ?

RéponseSignification pour l’expéditeurUtilisation habituelle pour un webhook
200 OKLa requête a été acceptée et traitée avec succès.Valeur par défaut pratique après validation et acceptation durable.
202 AcceptedLa requête a été acceptée pour traitement, mais celui-ci peut se poursuivre.Utile lorsque l’événement a été placé en toute sécurité dans une file d’attente, mais que le traitement métier est asynchrone.
204 No ContentLa requête a abouti et aucun corps de réponse n’est nécessaire.Convient lorsque le fournisseur accepte une réponse de succès vide.
400–499La requête est invalide, non autorisée ou inacceptable telle qu’elle a été envoyée.Charge utile mal formée, authentification échouée, signature invalide ou événement définitivement rejeté.
429 Too Many RequestsLe destinataire applique une limitation de débit.À utiliser uniquement lorsque le comportement de nouvelle tentative de l’expéditeur et votre politique de limitation sont compatibles.
500–599Le destinataire n’a pas pu accepter la requête en raison d’un problème côté serveur ou temporaire.Panne de base de données, échec de file d’attente, défaillance d’une dépendance ou erreur inattendue de l’application.

200 OK est souvent le choix le moins surprenant, car il est largement compris comme une réception réussie. 202 Accepted est également utile sur le plan sémantique lorsque le point de terminaison a accepté l’événement pour un traitement ultérieur. Aucun de ces codes n’est automatiquement correct : la documentation de l’expéditeur peut définir quelles réponses 2xx sont considérées comme réussies, et certains fournisseurs peuvent exiger un corps ou un type de contenu particulier.

Ne renvoyez pas une réponse 2xx simplement parce que la requête HTTP a atteint votre serveur. Si la vérification de la signature échoue ou si la charge utile ne peut pas être interprétée de manière sûre, une réponse 4xx est généralement plus exacte. À l’inverse, ne renvoyez pas une réponse 4xx pour une panne temporaire de base de données si l’événement pourrait aboutir ultérieurement. Une réponse 5xx donne à un expéditeur capable de réessayer la possibilité de livrer à nouveau l’événement, même si le fournisseur peut appliquer sa propre politique.

Comment gérer les délais d’expiration ?

Les valeurs de délai d’expiration des webhooks sont propres à chaque fournisseur. Il n’existe pas de délai HTTP universel utilisé par toutes les plateformes de suivi, et un expéditeur peut cesser d’attendre avant que votre application ne termine une opération lente. Considérez le délai documenté par l’expéditeur comme une limite maximale, et non comme un objectif. Votre point de terminaison doit normalement répondre bien avant cette limite.

L’erreur de conception la plus courante consiste à effectuer tout le travail en aval avant d’accuser réception du webhook. Un gestionnaire peut appeler successivement une base de données, un système de gestion des commandes, un service de notification et un pipeline d’analyse. Une seule dépendance lente peut entraîner un délai d’expiration côté expéditeur, même si votre application termine finalement le traitement. L’expéditeur peut alors réessayer, ce qui crée un traitement en double ou des mises à jour concurrentes.

Limitez le chemin synchrone au travail nécessaire pour prendre une décision d’acceptation sûre. Cela comprend généralement l’authentification de la requête, la validation de base du schéma, le stockage durable de l’événement et sa publication dans une file d’attente. Confiez l’enrichissement coûteux, les recherches auprès des transporteurs, les messages aux clients et les appels aux API tierces à un processus worker. Surveillez séparément le temps consacré à la réception, à la validation, à la conservation et à l’accusé de réception de l’événement, ainsi que le temps consacré à son traitement.

Un délai d’expiration n’est pas synonyme d’échec de l’opération métier. Du point de vue de l’expéditeur, un délai d’expiration signifie généralement qu’il n’a pas reçu de réponse de succès exploitable. Votre service peut avoir stocké l’événement avec succès juste avant la fermeture de la connexion. C’est pourquoi l’idempotence et la déduplication sont nécessaires, même lorsque le point de terminaison semble fiable.

Qu’est-ce qui provoque les nouvelles tentatives ?

Un expéditeur de webhook peut réessayer après une erreur de connexion, un délai d’expiration ou une réponse que son contrat classe comme non réussie. Le calendrier exact, le nombre maximal de tentatives, l’algorithme de temporisation progressive et la fenêtre de livraison varient selon le fournisseur. Ne promettez pas un nombre fixe de tentatives sauf si cela est indiqué dans la documentation du fournisseur.

Le destinataire doit supposer que des nouvelles tentatives peuvent se produire et les prendre délibérément en compte dans sa conception :

  • Utilisez un identifiant d’événement lorsqu’il est disponible. Stockez-le avec une contrainte d’unicité ou une clé de déduplication équivalente.
  • Rendez le traitement idempotent. L’application deux fois de la même mise à jour de l’état de livraison ne doit pas envoyer deux messages au client, créer deux remboursements ou faire progresser incorrectement une commande.
  • Conservez la charge utile d’origine ou un enregistrement d’audit utile. Cela facilite la relecture, l’analyse et le rapprochement.
  • Séparez l’acceptation du traitement. Un worker peut réessayer les échecs internes sans obliger l’expéditeur à répéter l’intégralité de l’échange HTTP.
  • Enregistrez les codes de réponse et la latence. Une hausse des réponses 5xx, des délais d’expiration ou des identifiants d’événement en double peut révéler une panne avant que les utilisateurs ne signalent l’absence de mises à jour de suivi.

Un événement en double doit généralement recevoir une réponse de succès si l’événement d’origine a déjà été accepté durablement. Renvoyer une erreur pour chaque doublon peut déclencher des nouvelles tentatives inutiles. Le point de terminaison peut enregistrer que l’événement a déjà été vu, ignorer l’action métier répétée et renvoyer la même classe de succès que celle utilisée pour un événement nouvellement accepté.

Quand renvoyer une réponse 4xx, 429 ou 5xx ?

Renvoyez une réponse 4xx lorsqu’il est peu probable que la nouvelle tentative de la même requête résolve le problème. Il peut s’agir d’une signature invalide, d’une authentification obligatoire manquante, d’un format de charge utile non pris en charge ou d’une requête qui enfreint une règle de validation permanente. Avant de choisir 4xx, vérifiez si l’expéditeur considère ce statut comme un échec définitif. Certaines plateformes disposent de leurs propres règles concernant les livraisons échouées.

Utilisez 429 avec précaution. HTTP définit 429 pour la limitation de débit, et l’en-tête Retry-After peut indiquer quand une nouvelle tentative est appropriée. Toutefois, tous les expéditeurs de webhooks n’interprètent pas 429 de la même manière. Si votre file d’attente est pleine ou si votre service est surchargé, vérifiez que le fournisseur réessaiera en toute sécurité et que son calendrier de nouvelles tentatives n’aggravera pas la surcharge. Une file d’ingestion limitée et un plan de contrôle de la pression sont généralement préférables à des échecs imprévisibles.

Renvoyez une réponse 5xx lorsque le destinataire ne peut pas accepter l’événement en toute sécurité en raison d’un problème temporaire. Cela comprend une base de données indisponible, l’échec de l’écriture dans une file d’attente durable ou une erreur interne ayant empêché la validation ou la conservation. Renvoyer 200 tout en supprimant silencieusement l’événement rend la récupération plus difficile, car l’expéditeur n’a aucune raison de réessayer.

Évitez de vous fier aux redirections telles que 301, 302 ou 307 pour la livraison des webhooks. La gestion des redirections diffère selon les clients, et la redirection d’une requête signée peut créer une ambiguïté concernant la destination, la méthode et le corps. Configurez plutôt le fournisseur avec le point de terminaison HTTPS final.

Une politique de réponse fiable pour les événements de suivi

Pour la plupart des intégrations de webhooks de suivi, la politique suivante constitue un bon point de départ :

  1. Renvoyer 200 ou 202 après que l’événement a été authentifié et stocké durablement ou placé dans une file d’attente fiable.
  2. Renvoyer une réponse 4xx pour une signature invalide, une authentification invalide ou une charge utile définitivement inutilisable, conformément aux règles documentées du fournisseur.
  3. Renvoyer 5xx lorsqu’un échec temporaire empêche l’acceptation durable.
  4. Renvoyer une réponse de succès pour un doublon correctement reconnu, tout en empêchant les effets métier en double.
  5. Conserver un gestionnaire rapide et mesurer sa latence d’accusé de réception.
  6. Tester les scénarios de délai d’expiration, de nouvelle tentative, de doublon, de désordre, de requête mal formée et de panne du fournisseur avant le lancement en production.

Si vous intégrez une API de suivi, commencez par consulter la documentation des webhooks du fournisseur et confirmez les codes de succès acceptés, la méthode de signature des requêtes, le délai d’expiration, les déclencheurs de nouvelles tentatives, le schéma de la charge utile et l’identifiant d’événement. Pour les intégrations 17TRACK, la documentation officielle de l’API de suivi est l’endroit approprié pour vérifier le contrat propre au fournisseur, plutôt que de le déduire des pratiques HTTP générales.

Liste de contrôle de l’implémentation

  • Le point de terminaison est accessible via HTTPS et possède une URL de production stable.
  • L’authentification et la vérification de la signature ont lieu avant le traitement métier.
  • La requête brute ou une représentation vérifiable est conservée lorsque cela est nécessaire pour les vérifications de signature et le dépannage.
  • L’événement est conservé avant l’envoi de la réponse de succès.
  • Les livraisons en double sont sûres et ne répètent pas les actions irréversibles.
  • Les workers peuvent réessayer le traitement interne indépendamment du cycle de nouvelles tentatives HTTP de l’expéditeur.
  • Les journaux incluent l’ID de l’événement, l’heure de livraison, le code de réponse, l’état du traitement et l’ID de corrélation sans exposer de secrets.
  • Les alertes distinguent les délais d’expiration du point de terminaison, les échecs de validation 4xx, les pannes 5xx, les retards de file d’attente et les livraisons en double.
  • Le comportement documenté du fournisseur a été testé avec des événements réels ou de bac à sable.

FAQ

200 OK est-il préférable à 202 Accepted pour un webhook ?

Aucun des deux n’est universellement préférable. Utilisez 200 OK lorsque la requête a été acceptée et que votre intégration traite la réponse comme un succès général. Utilisez 202 Accepted lorsque l’événement a été accepté pour un traitement asynchrone. Vérifiez que l’expéditeur considère la réponse 2xx choisie comme réussie.

Un point de terminaison de webhook doit-il attendre que la mise à jour du suivi soit entièrement traitée ?

Généralement, non. Il doit attendre uniquement que l’événement soit authentifié, validé et accepté durablement. Les opérations longues doivent normalement avoir lieu après l’accusé de réception afin qu’une dépendance lente ne provoque pas un délai d’expiration et une nouvelle tentative évitables.

Que doit-il se passer lorsque le même événement de suivi arrive deux fois ?

Reconnaissez-le à l’aide de l’ID d’événement du fournisseur ou d’une clé équivalente soigneusement conçue, ignorez les effets secondaires en double et renvoyez une réponse de succès si l’événement a déjà été accepté. Cela rend les nouvelles tentatives sûres sans masquer les nouveaux échecs de traitement.

Une signature invalide doit-elle renvoyer 400 ou 401 ?

Le choix dépend de votre modèle d’authentification et des attentes documentées du fournisseur. Les deux peuvent communiquer un rejet, mais la cohérence est plus importante que le choix universel de l’un d’eux. N’accusez pas réception d’un événement dont vous ne pouvez pas vérifier l’authenticité.

Une réponse 5xx provoque-t-elle toujours une nouvelle tentative ?

Non. De nombreux systèmes de webhook réessaient en cas de délai d’expiration ou d’erreur serveur, mais les déclencheurs et les calendriers de nouvelles tentatives dépendent du fournisseur. Considérez les nouvelles tentatives comme un comportement d’intégration documenté et vérifiez-le dans un environnement de test.

Sources