Mises à jour en temps réel avec les Webhooks

Aperçu

Les webhooks permettent à vos applications de recevoir des notifications en temps réel lorsque des événements se produisent dans DataDocks. Plutôt que d’interroger l’API à intervalles réguliers pour détecter des changements, votre application peut être notifiée de façon asynchrone lorsqu’un rendez-vous est créé, mis à jour ou que son statut change.

Quand utiliser les webhooks

• Mises à jour d’inventaire en temps réel lors de l’arrivée des expéditions
• Notifications automatiques aux transporteurs lors de l’approbation des rendez-vous
• Déclenchement de flux de travail personnalisés lors du changement de statut d’un rendez-vous
• Synchronisation avec votre ERP, WMS ou TMS en temps réel
• Suivi des activités d’intégration en complément d’un rapprochement périodique via l’API ; les webhooks ne constituent pas un historique complet d’audit

Fonctionnement des webhooks

1. Sélectionnez les événements pour lesquels vous souhaitez recevoir des notifications et créez un billet de support avec l’URL qui recevra les webhooks
2. Lorsque ces événements se produisent, DataDocks envoie une requête HTTP POST à votre URL
3. Votre serveur traite l’événement et répond avec le statut 200 OK

Implémentation des webhooks

Les webhooks DataDocks sont configurés au niveau de l’emplacement, avec une seule destination par type de notification. Le support peut vous aider à activer les événements dont vous avez besoin et vérifier la configuration des notifications de votre emplacement.

Authentification

Chaque requête webhook inclut les en-têtes suivants :

En-tête	Description
x-datadocks-webhooks-token	Jeton d’authentification spécifique à l’emplacement
x-datadocks-host	Identifiant de l’hôte pour l’emplacement (ex. : subdomain.datadocks.com)
content-type	Toujours défini sur application/json

Charge utile du webhook

La charge utile du webhook utilise le format de réponse de l’API des rendez-vous. L’exemple suivant présente certains champs :

{
  "id": 123,
  "appointment_number": 456,
  "state": "arrived",
  "carrier_name": "Express Logistics",
  "scheduled_at": "2023-10-15T14:00:00Z",
  "arrived_at": "2023-10-15T14:22:17Z",
  "dock": "Dock 5",
  "yard": null
}

La charge utile complète contient tous les détails du rendez-vous, les listes d’emballage, les notes et les documents disponibles. Consultez le schéma de réponse lié pour les noms de champs et leurs descriptions.

La charge utile n’indique pas le type de notification. Utilisez un chemin de point de terminaison différent pour chaque type si vous devez les distinguer. Les données peuvent inclure des modifications effectuées après l’événement initial et les requêtes peuvent arriver dans un ordre différent.

Types de notifications disponibles

Les webhooks peuvent être configurés pour différents types de notifications liées aux rendez-vous :

Type de notification	Description
unscheduled_appointment_created	Un rendez-vous non planifié est créé
appointment_pending	Un rendez-vous est en attente d’approbation
appointment_approved	Un rendez-vous est approuvé, y compris l’approbation automatique
appointment_arrived	Un camion est arrivé pour un rendez-vous
appointment_started	Le chargement/déchargement commence
appointment_completed	Le chargement/déchargement est terminé
appointment_drop_trailer_completed	Un rendez-vous de dépôt de remorque est terminé
appointment_left	Un camion quitte après un rendez-vous
appointment_cancelled	Un rendez-vous est annulé
appointment_schedule_changed	La date ou l’heure planifiée d’un rendez-vous change
appointment_note_added	Une note est ajoutée à un rendez-vous existant
appointment_delayed	Un rendez-vous a été marqué comme retardé
appointment_no_show	Un rendez-vous a été marqué comme "absence"
appointment_late	Un rendez-vous a été marqué comme "en retard"
appointment_edit	Les détails d’un rendez-vous changent sans notification de statut ou d’horaire distincte
appointment_document_added	Un document est ajouté à un rendez-vous existant
appointment_booked_externally	Un rendez-vous est créé via le Portail de réservation

appointment_edit ne couvre pas tous les changements. Abonnez-vous aussi aux événements de statut et d’horaire nécessaires. Si une mise à jour modifie à la fois le statut et la date/heure prévue, la notification de statut prend le dessus. Un changement de durée seulement ne déclenche pas appointment_schedule_changed.

Sécurité

Les URLs de webhook en production doivent utiliser HTTPS. L’authentification s’effectue par l’en-tête X-DataDocks-Webhooks-Token, qui contient un jeton spécifique à votre emplacement.

Vérification de l’authenticité du webhook

Pour vérifier qu’une requête webhook provient bien de DataDocks :

1. Conservez en lieu sûr le jeton webhook de votre emplacement dans votre application
2. Lors de la réception d’un webhook, comparez le jeton dans l’en-tête X-DataDocks-Webhooks-Token avec votre jeton enregistré
3. Ne traitez le webhook que si les jetons correspondent

Il s’agit d’une vérification par jeton partagé, et non d’une signature de charge utile. Ne consignez pas le jeton dans les journaux.

Bonnes pratiques

1. Répondez rapidement — Les requêtes webhook doivent être accusées de réception avec le code de statut 200 le plus rapidement possible
2. Traitez de façon asynchrone — Placez le webhook en file d’attente pour un traitement en arrière-plan si des opérations complexes sont nécessaires
3. Relancez le traitement et effectuez un rapprochement — Relancez les échecs après avoir enregistré la charge utile et utilisez un rapprochement périodique via l’API pour récupérer les requêtes manquées. Les relances côté récepteur ne permettent pas de récupérer des requêtes qui ne sont jamais arrivées
4. Vérifiez toujours le jeton — N’ignorez jamais la vérification du jeton en production
5. Surveillez les échecs — Surveillez votre serveur de réception et votre file d’attente de traitement ; les journaux DataDocks ne capturent pas les codes d’erreur HTTP
6. Gérez les demandes en double — Rendez le traitement idempotent (sûr en cas de répétition)

Délais et comportement de livraison

Vérifiez et stockez la charge utile avant d’accuser réception de la requête. Les tentatives de connexion expirent après cinq secondes ; les requêtes après dix secondes. Les connexions échouées et les retours d’erreur HTTP ne déclenchent pas de nouvelle tentative automatique, donc utilisez un rapprochement API pour récupérer les mises à jour manquées. Des demandes en double sont possibles.

Dépannage

La page des paramètres de l’emplacement comporte une section webhooks où vous pouvez consulter les points de terminaison configurés et les journaux de livraison.

Problème	Cause possible	Solution
Événements manquants	URL injoignable ou événements non configurés	Vérifiez votre point de terminaison et contactez le support pour vérifier la configuration des événements
Jeton invalide	Incompatibilité du jeton ou configuration	Vérifiez que le jeton de webhook est correct
Erreurs serveur	Votre point de terminaison échoue	Consultez les journaux de votre serveur

Configuration des webhooks

Pour configurer des webhooks pour votre emplacement DataDocks, veuillez contacter notre équipe de soutien en fournissant les informations suivantes :

1. L’emplacement (ou les emplacements) pour lesquels vous souhaitez activer les webhooks
2. Les types de notifications que vous souhaitez recevoir
3. L’URL HTTPS du point de terminaison de chaque type de notification (une seule destination par type et par emplacement)

Notre équipe procédera à la configuration appropriée des webhooks et vous remettra le jeton webhook de votre emplacement.

Journaux des webhooks

Les journaux de webhooks dans les paramètres de l’emplacement affichent les charges utiles envoyées et les erreurs de connexion. Ils n’incluent pas la réponse de votre point de terminaison ni la confirmation du traitement réussi ; vérifiez donc également les journaux de votre serveur. Si une livraison attendue manque, contactez le support en fournissant l’ID du rendez-vous, le type de notification et l’heure approximative.