info-icon


Guide du développeur de webhooks

Introduction

Les webhooks de suivi FedEx fournissent des mises à jour de l’envoi quasi en temps réel tout au long du cycle de vie de l’envoi.

Contrairement aux API de suivi, qui nécessitent que les applications demandent le statut des envois, les webhooks transmettent automatiquement les mises à jour des envois dès que de nouvelles informations sont disponibles.

Ce guide traite des sujets suivants :

  • Trois principes d’intégration
  • Fonctionnement des webhooks
  • Traitement des charges utiles de webhook
  • Notifications aux clients
  • Horodatages
  • Bonnes pratiques et problèmes d’intégration courants

Trois principes d’intégration

Les intégrations webhook réussies reposent sur trois principes.

Considérez chaque charge utile de webhook comme une mise à jour de l’état d’un envoi

Ne supposez pas que chaque charge utile représente une nouvelle étape de suivi. FedEx publie une nouvelle charge utile dès que de nouvelles informations sur l’envoi sont disponibles.

Une charge utile peut contenir :

  • Un nouvel événement de suivi ;
  • Des prévisions de livraison mises à jour ;
  • Des informations sur la preuve de livraison ;
  • Informations relatives au destinataire
  • D’autres modifications des données d’envoi.

Plusieurs charges utiles peuvent être associées à une même étape de suivi tout en contenant des informations différentes sur l’envoi.

Stockez et fusionnez les données d’envoi

Chaque charge utile peut contenir des informations nouvelles ou mises à jour sur l’envoi. Stockez chaque charge utile de webhook et fusionnez les nouvelles informations avec l’enregistrement d’envoi existant.

Ne remplacez pas l’enregistrement d’envoi existant par la charge utile la plus récente. À la place, conservez les données d’envoi reçues précédemment et intégrez les nouvelles informations afin de maintenir un enregistrement d’envoi complet et à jour tout au long du cycle de vie de l’envoi.

Utilisez les règles métier pour piloter les actions

Utilisez des règles métier pour déterminer quand mettre à jour les systèmes ou avertir les clients.

Ne déclenchez pas d’actions uniquement à partir d’un code d’événement. Avant de mettre à jour les applications destinées aux clients, ou d’envoyer des notifications, évaluez :

  • Étapes de suivi
  • Disponibilité de l’envoi
  • Heure de notification
  • Exigences métier

Modèle de traitement recommandé

Le diagramme suivant illustre la façon dont les trois principes d’intégration des webhooks fonctionnent ensemble dans une mise en œuvre type. Chaque charge utile de webhook est traitée comme une mise à jour de l’état d’un envoi, est fusionnée dans un enregistrement centralisé des envois, et est évaluée à l’aide de règles métier avant la mise à jour des applications, ou l’envoi de notifications aux clients.


Fonctionnement des webhooks

FedEx publie une nouvelle charge utile de webhook dès que de nouvelles informations sur l’envoi changent ou deviennent disponibles. Un envoi peut générer plusieurs charges utiles tout au long de son cycle de vie, y compris plusieurs charges utiles associées à la même étape de suivi.

Des charges utiles supplémentaires peuvent inclure :

  • Étapes de suivi : Pris en charge, En transit, En cours de livraison et Livré.
  • Données de l’envoi : preuve de livraison (PPOD), preuve de livraison avec signature (SPOD), preuve de livraison GPS (GPS POD) et informations sur le destinataire.
  • Mises à jour des prévisions de livraison : modifications de la date et de l’heure de livraison estimées.
  • Exceptions de livraison : mises à jour et motifs des exceptions liées aux envois et à la livraison.
  • Mises à jour des métadonnées d’envoi : Mises à jour d’adresse, références, et détails du service.
  • Corrections opérationnelles : jalons de suivi supplémentaires et mises à jour de previousEvents.

Remarque : la preuve par image n’est pas disponible pour tous les envois livrés. La disponibilité dépend du type de livraison, des exigences en matière de signature et d’autres règles métier.

Chaque charge utile représente le dernier état connu de l’envoi. Traitez chaque charge utile afin de garantir que votre dossier d’envoi reste complet et à jour.

Comprendre les mises à jour des webhooks

L’exemple suivant montre comment plusieurs charges utiles de webhook peuvent être générées pour le même envoi tout au long de son cycle de vie. Certaines charges utiles introduisent une nouvelle étape de suivi. D’autres ajoutent des informations sur l’envoi, telles que des prévisions de livraison, des données de Preuve de livraison ou des détails sur l’envoi.

Important : plusieurs charges utiles de webhook peuvent être générées pour la même étape de suivi. Traitez chaque charge utile afin que les nouvelles informations sur l’envoi soient intégrées à l’enregistrement d’envoi.


Traitement des charges utiles de webhook

Traitez chaque charge utile de webhook comme une mise à jour de l’état d’un envoi.

Ne supposez pas que chaque charge utile de webhook représente une nouvelle étape de suivi. FedEx envoie une nouvelle charge utile dès que de nouvelles informations sur l’envoi sont disponibles. Par exemple, un envoi livré peut générer des charges utiles supplémentaires lorsque des informations de preuve de livraison, des informations sur le destinataire ou d’autres données sur l’envoi sont ajoutées ou mises à jour.

Pour chaque charge utile, demandez-vous :

  • Quelle étape de suivi a changé ?
  • Quelles informations sur l’envoi ont changé ?
  • La mise à jour affecte-t-elle une application destinée aux clients ?
  • La mise à jour déclenche-t-elle une notification ?

Traitez l’historique des envois

Surveillez à la fois scanEvent et previousEvents.

  • scanEvent contient l’étape de suivi actuelle associée à la charge utile.
  • previousEvents contient un historique supplémentaire de l’envoi, notamment des étapes qui peuvent ne pas figurer dans le scanEvent actuel.

Certaines étapes de suivi apparaissent dans previousEvents au lieu d’être publiées sous la forme d’un nouveau scanEvent. Les applications qui ne traitent que scanEvent peuvent manquer des mises à jour de l’envoi et générer des historiques d’envoi incomplets. Traitez les deux collections afin d’obtenir une vue complète de l’envoi.

Tenez à jour un dossier d’envoi

Stockez chaque charge utile de webhook et fusionnez les nouvelles informations avec l’enregistrement d’envoi existant.

Un dossier d’envoi complet offre une visibilité quasi en temps réel sur :

  • les tableaux de bord de suivi des envois ;
  • les applications du service Clients ;
  • les système de gestion des commandes (OMS).

Mettez à jour l’enregistrement d’envoi avec chaque charge utile afin de conserver la vue la plus précise et complète de l’envoi.


Notifications aux clients

Choisissez une stratégie de notification en fonction des exigences de votre entreprise et du niveau de détail sur l’envoi que vous souhaitez fournir.

Les webhooks de suivi FedEx envoient des mises à jour concernant les jalons de suivi et les modifications des données d’envoi quasiment en temps réel. Utilisez des règles métier pour déterminer quelles mises à jour sont pertinentes pour votre entreprise et lesquelles peuvent être ignorées.

Les stratégies de notification courantes sont les suivantes :

Notifications en temps quasi réel

Envoyez les notifications immédiatement après la survenue d’une étape de suivi.

Avantages

  • Communication client la plus rapide ;
  • Latence la plus faible.

À noter : des informations supplémentaires sur l’envoi peuvent ne pas encore être disponibles.

Notifications enrichies

Veuillez patienter quelques minutes après une étape de suivi afin que des informations supplémentaires sur l’envoi puissent arriver.

Par exemple, après une étape « Livré », veuillez patienter quelques minutes pour récupérer :

  • Preuve de livraison (POD)
  • Preuve de livraison avec signature (PDLS)
  • Preuve de livraison GPS
  • Informations relatives au destinataire

Avantages

  • Des mises à jour de l’envoi plus complètes pour les clients ;
  • Moins de notifications de suivi ;
  • Moins de contacts avec l’assistance clients.

FedEx recommande d’attendre environ cinq minutes après une étape de suivi indiquant la livraison, car les informations de preuve de livraison sont souvent ajoutées peu après l’événement de livraison initial.

Recommandations concernant l’heure de notification

L’heure d’envoi des notifications varie selon le client et le cas d’usage. Toutefois, les recommandations suivantes sont couramment utilisées pour les notifications post-achat destinées aux destinataires. Pour les autres types de notifications (utilisateurs professionnels, représentants du service Clients, etc.), veuillez choisir une stratégie de notification adaptée à votre cas d’usage.

  • Livraison estimée : patientez environ 15 minutes après que la date d’engagement et la première date de livraison estimée (EDD) sont toutes deux disponibles.
  • En cours de livraison : envoyez immédiatement ou selon le calendrier de votre entreprise (par exemple, tous les jours à 08h00).
  • Livré : patientez environ 5 minutes pour permettre aux informations complémentaires relatives à la livraison d’arriver.
  • Tentative de livraison : appliquez la même approche que pour le statut Livré afin de permettre aux informations de livraison d’arriver.

Créer des règles de notification basées sur les données de l’entreprise

Toutes les mises à jour d’un envoi ne nécessitent pas de notification. Définissez des règles de notification qui répondent aux exigences de votre entreprise.

Approche recommandée

Ne déclenchez pas de notifications uniquement en fonction de eventCode.

Évaluez :

  • les étapes de suivi ;
  • les données d’envoi requises ;
  • les règles commerciales.

Générez des notifications uniquement lorsque les informations requises sont disponibles.

Cette approche contribue à prévenir :

  • les notifications en double ;
  • les informations de livraison manquantes ;
  • les notifications de livraison incomplètes ;
  • les notifications de suivi inutiles.

Horodatages

Veuillez utiliser l’horodatage approprié en fonction de votre cas d’usage.

  • eventCreateTime : quand l’événement lié à l’envoi s’est produit. Utilisez-le pour l’historique de suivi destiné aux clients.
  • Heure d’envoi du message : lorsque FedEx a envoyé la charge utile du webhook. Utilisez-le uniquement pour le débogage et la surveillance, et non pour les expériences destinées aux clients.

eventCreateTime indique quand l’événement lié à l’envoi s’est produit. FedEx ne met pas cette valeur à jour lorsque des informations supplémentaires sur l’envoi sont ajoutées ultérieurement. Par exemple, un événement indiquant que l’envoi a été livré conserve sa valeur eventCreateTime d’origine, même si des charges utiles ultérieures ajoutent des informations de preuve de livraison ou d’autres mises à jour concernant l’envoi. Par conséquent, eventCreateTime doit être utilisé pour déterminer quand l’événement s’est produit, et non quand les informations relatives à l’envoi ont été ajoutées.

Dans certains cas, l’heure de l’événement peut ne pas être disponible. Dans ce cas, l’horodatage peut contenir une valeur par défaut de 00:00:00. Des charges utiles supplémentaires peuvent inclure un horodatage plus précis lorsqu’il devient disponible.


Bonnes pratiques et problèmes d’intégration courants

Meilleures pratiques

  • Traitez chaque charge utile de webhook : chaque message peut contenir un nouvel événement de suivi ou une mise à jour des données d’envoi.
  • Fusionnez les mises à jour incrémentielles dans votre dossier d’envoi existant.
  • Surveillez à la fois scanEvent et previousEvents afin de capturer l’historique complet de l’envoi.
  • Déclenchez les notifications destinées aux clients en fonction des règles métier, et pas uniquement des événements bruts.
  • Prévoyez du temps pour les enrichissements attendus (par exemple, PPOD, SPOD, GPS) avant d’informer les clients.
  • Concevez un traitement idempotent et résilient qui gère les messages en double et dans le désordre.

Problèmes d’intégration courants

  • Supposer que chaque charge utile représente une nouvelle étape de suivi.
  • Remplacer l’enregistrement d’envoi par la charge utile la plus récente.
  • S’appuyer uniquement sur scanEvent.
  • Déclencher des notifications uniquement en fonction de eventCode.
  • Supposer que la première charge utile livrée contient tous les détails de livraison.
  • Supposer que les messages de webhook n’arrivent qu’une seule fois ou dans l’ordre chronologique.

Récapitulatif

Traitez chaque charge utile de webhook comme une mise à jour de l’état d’un envoi. Stockez et fusionnez les mises à jour de l’envoi, surveillez à la fois scanEvent et previousEvents, et utilisez les règles métier pour déterminer quand mettre à jour les applications ou avertir les clients.

Cette approche contribue à garantir une visibilité précise de l’envoi, un historique de suivi complet et des communications avec les clients mieux éclairées.