Pourquoi utiliser les webhooks ?

ChannelDock fournit des webhooks pour informer votre système immédiatement lorsqu’un changement survient dans votre compte. Au lieu d’interroger l’API selon un planning, vous recevez automatiquement une notification lorsqu’une commande est créée ou mise à jour, qu’une expédition est créée, que les niveaux de stock changent ou qu’un retour est enregistré. Les webhooks vous aident à automatiser les processus et à réduire les requêtes API inutiles.

Fonctionnalités clés

• Timing des événements : Les webhooks se déclenchent quelques minutes après qu’un événement se produit, vous offrant des mises à jour quasi en temps réel.
• Cohérence du payload : Le payload JSON d’un webhook correspond à la structure renvoyée par l’endpoint API correspondant.
• Nouvelles tentatives automatiques : Si ChannelDock ne peut pas livrer un webhook, jusqu’à cinq tentatives sont effectuées avec des délais croissants (0, 30, 60, 120 et 240 secondes). Après dix échecs de livraison, le webhook est désactivé par sécurité.
• Sécurité : Chaque webhook peut avoir sa propre clé secrète. ChannelDock utilise cette clé secrète pour calculer une signature numérique afin que vous puissiez vérifier l’authenticité du payload.

Configurer un webhook

1. Accédez aux paramètres : Connectez-vous à ChannelDock et allez dans Settings → API & Webhooks. Vous verrez deux sections : API keys et Webhooks.

2. Créez un nouveau webhook : Cliquez sur Create new webhook. Une fenêtre « Webhook Configuration » s’affiche.

3. Remplissez les champs :

   • Webhook name : Choisissez un nom interne descriptif (par exemple, « Order updates »).
   • Webhook URL : Saisissez l’URL de votre endpoint où ChannelDock peut envoyer une requête HTTP POST. Assurez-vous que cette URL est accessible publiquement et répond dans les 5 secondes.
   • Event to trigger webhook : Sélectionnez le type d’événement pour lequel vous souhaitez des notifications. Les événements possibles incluent order.created, order.updated, order.status.changed, order.deleted, shipment.created, stock.updated, return.created, return.handled et return.product.updated.
   • Status : Laissez sur Active. Les webhooks sont automatiquement désactivés après 10 tentatives de livraison échouées.
   • Webhook secret (optional but recommended) : Fournissez votre propre secret ou cliquez sur Generate pour en créer un robuste. ChannelDock utilise ce secret pour calculer une signature hash HMAC‑SHA256 afin que vous puissiez vérifier le payload.

4. Enregistrez : Cliquez sur Save webhook. ChannelDock enregistre votre webhook et enverra les événements du type sélectionné vers votre endpoint.

Structure du payload et événements

Lorsqu’un événement choisi se produit, ChannelDock envoie un payload JSON à votre endpoint. Le payload contient au minimum les champs suivants :

{   
  "event": "order.created",  
  "payload": {   
    ...  
  },  
  "signature": "<hash>" (Optional but recommended)  
}

• event – l’événement pour lequel le webhook a été configuré (par exemple order.created).
• payload – contient les détails de la commande, de l’expédition, du retour ou de la mutation de stock. La structure correspond à la réponse API de l’objet correspondant.
• signature – présente uniquement lorsqu’un secret est configuré. Il s’agit d’une signature HMAC‑SHA256 du payload complet, sauf le champ signature lui-même.

Vérifier la signature

Il est important de s’assurer que le webhook a été envoyé par ChannelDock et que le payload n’a pas été altéré. Pour cela, comparez la signature fournie par ChannelDock avec votre propre calcul.

En interne, ChannelDock signe chaque payload en calculant un hash HMAC‑SHA256 des données JSON avec le secret que vous avez configuré. Le hash résultant est ajouté comme champ signature dans le payload.

Vérifier la signature dans votre application

1. Recevez le webhook : Analysez le JSON et stockez temporairement la valeur du champ signature. Supprimez le champ signature du payload avant de calculer le hash.
2. Générez un hash : Utilisez votre secret key avec la méthode de hash HMAC-SHA256 pour créer une nouvelle signature. Exécutez cela sur les données JSON reçues (sans le champ signature).
3. Comparez les hash : Si le hash calculé correspond exactement à la signature reçue, vous pouvez faire confiance à l’authenticité et à l’intégrité du payload.

Conseils pour un traitement sécurisé

• Attribuez à chaque webhook son propre secret et faites-le tourner régulièrement.
• Utilisez une fonction de comparaison en temps constant (par exemple hash_equals en PHP) pour prévenir les attaques par timing.
• Effectuez des vérifications supplémentaires sur le contenu du payload (par exemple vérifiez que la commande existe) avant d’exécuter des actions.

Bonnes pratiques

ChannelDock recommande plusieurs pratiques pour traiter les webhooks de manière sûre et fiable :

• Réponse HTTP‑200 : Faites renvoyer par votre endpoint un HTTP 200 OK dès que le payload a été reçu avec succès. Sinon, ChannelDock considère la tentative comme échouée et réessaie.
• Idempotence : Les messages webhook peuvent parfois être envoyés deux fois (par exemple en raison de problèmes réseau ou de nouvelles tentatives). Assurez-vous que votre logique de traitement est idempotente pour éviter les doublons.
• Surveillance : Utilisez le tableau de bord ChannelDock pour surveiller l’état de vos webhooks et identifier les erreurs.
• Gestion du payload : Assurez-vous que votre endpoint peut gérer de grands payloads et répond dans un délai raisonnable (≤ 5 secondes). Les webhooks sont automatiquement désactivés après dix échecs de livraison.