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 immédiatement notifiée 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
• Historique d’audit de toute l’activité des rendez-vous

Fonctionnement des webhooks

1. Sélectionnez les événements pour lesquels vous souhaitez recevoir une notification 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. Chaque emplacement peut disposer de webhooks pour différents types de notifications.

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 à application/json

Charge utile du webhook

La charge utile (payload) du webhook contient l’ensemble des données du rendez-vous au format JSON, tel qu’affiché dans le modèle de vue des rendez-vous. On y retrouve tous les détails pertinents du rendez-vous, tels que :

{
  "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_name": "Dock 5"
  // Données complètes du rendez-vous...
}

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é
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	L’opération de dépôt de remorque est terminée
appointment_left	Un camion quitte après un rendez-vous
appointment_cancelled	Un rendez-vous est annulé
appointment_schedule_changed	L’horaire d’un rendez-vous a été modifié
appointment_note_added	Une note a été ajoutée à un rendez-vous
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	Un rendez-vous a été modifié

Sécurité

DataDocks transmet les webhooks via un serveur mandataire sécurisé afin d’assurer une livraison fiable et une communication sécurisée. L’authentification se fait via l’en-tête X-DataDocks-Webhooks-Token, qui contient un jeton propre à votre emplacement.

Vérification de l’authenticité du webhook

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

1. Conservez de façon sécuritaire 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

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. Implémentez vos propres relances — Si votre système exige un traitement garanti, implémentez votre propre logique de relance
4. Vérifiez toujours le jeton — N’ignorez jamais la vérification du jeton en production
5. Surveillez les échecs — Configurez des alertes pour les échecs de livraison des webhooks

Dépannage

La page des paramètres de l’emplacement comporte une section webhooks où vous pouvez consulter les journaux des webhooks et tester leur envoi.

Problème	Cause possible	Solution
Événements manquants	L’URL du webhook est injoignable	Vérifiez les journaux et le pare-feu serveur
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 de l’endpoint où les webhooks doivent être envoyés

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

Journaux des webhooks

DataDocks conserve des journaux de toutes les tentatives d’envoi de webhooks, incluant les charges utiles envoyées et tout message d’erreur reçu. Ces journaux aident au dépannage et à l’audit de la livraison des webhooks. Si vous rencontrez des problèmes avec les webhooks, veuillez contacter le support en mentionnant les identifiants de rendez-vous concernés ou visiter la page des paramètres de l’emplacement pour consulter les journaux des webhooks.