Browse all articles

Configurer les webhooks dans ChannelDock

Last updated

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. Lorsqu’un secret est défini, ChannelDock signe chaque livraison avec une signature HMAC-SHA256 dans l’en-tête X-Channeldock-Signature, ce qui vous permet de vérifier qu’une requête provient réellement de ChannelDock.

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.picking, order.picked, 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 (optionnel mais recommandé) : Indiquez votre propre secret ou cliquez sur Générer pour créer un secret robuste. ChannelDock utilise ce secret pour signer chaque livraison, ce qui vous permet de vérifier que la requête vient de ChannelDock et n’a pas été modifiée en route.

  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

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

{   
  "event": "order.created",  
  "payload": {   
    ...  
  },  
  "signature": "<hash>" (obsolète, voir ci-dessous)  
}
  • 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 du mouvement de stock. La structure correspond à la réponse de l’API pour l’objet concerné.
  • signature – présent uniquement lorsqu’un secret est configuré. Il s’agit de l’ancienne signature, désormais obsolète ; vérifiez plutôt l’en-tête X-Channeldock-Signature.

Vérifier la signature

L’URL de votre webhook doit être accessible publiquement, et la requête ne contient aucune autre preuve de son expéditeur — pas de clé d’API, pas de mot de passe. Tout ce qui atteint cette URL ressemble donc, pour votre endpoint, à une véritable livraison ChannelDock : une URL divulguée par un fichier de log, un proxy ou un ticket de support, ou une livraison antérieure que quelqu’un a capturée et renvoyée. Si vous agissez sur le contenu sans vérification, un faux stock.updated pourrait mettre votre stock à zéro, ou un faux order.updated marquer une commande comme expédiée dans votre propre système.

La signature est cette preuve manquante. Seuls vous et ChannelDock connaissez le secret : vous êtes donc les seuls à pouvoir produire une valeur qui corresponde à la livraison que vous avez sous les yeux.

Dès que vous définissez un secret de webhook, chaque livraison pour ce webhook arrive avec un en-tête HTTP supplémentaire :

X-Channeldock-Signature: sha256=8b415f2c0cd241a21109e007942b6ce43cbfcf97f7b2d7829084258c0ae0a66f

Cette valeur est un hachage HMAC-SHA256 du corps de la requête, calculé avec votre secret comme clé. Vous calculez le même hachage de votre côté et vérifiez que les deux sont identiques. Si aucun secret n’est défini, l’en-tête n’est pas envoyé.

Vérifier la signature dans votre application

  1. Lisez le corps brut. Prenez le corps de la requête sous forme de texte ou d’octets, avant que le JSON ne soit analysé. La plupart des frameworks analysent le JSON et jettent le texte original : demandez-le explicitement avec php://input en PHP, $request->getContent() en Laravel, request.get_data() en Flask, request.body en Django, request.raw_post en Rails, ou express.json({ verify: (req, res, buf) => { req.rawBody = buf } }) en Express.
  2. Lisez l’en-tête. Prenez X-Channeldock-Signature et retirez le préfixe sha256=. Recherchez l’en-tête sans tenir compte de la casse — selon la connexion, il arrive sous la forme x-channeldock-signature.
  3. Calculez votre propre hachage. Un HMAC-SHA256 du corps brut avec votre secret de webhook comme clé, écrit en hexadécimal. En PHP : hash_hmac('sha256', $raw, $secret).
  4. Comparez avec une fonction à temps constant telle que hash_equals. Si les deux sont identiques, la livraison est authentique et vous pouvez la traiter. Sinon, renvoyez HTTP 401 et ignorez le corps. N’analysez le JSON qu’après la réussite de cette étape.

Important : hachez le corps exactement tel que vous l’avez reçu. Une signature est un hachage d’octets, non du sens du JSON. N’analysez donc pas le JSON pour le reconvertir ensuite en texte et le hacher. Deux langages peuvent écrire un JSON qui signifie exactement la même chose sans être le même texte : PHP écrit une barre oblique c\/o là où Node.js et Python écrivent c/o. Cela se relit comme des données identiques, mais produit un hachage totalement différent. Ne retirez pas non plus le champ signature avant de hacher — il fait partie du corps qui a été signé.

L’ancien champ signature

Avant l’existence de l’en-tête, ChannelDock plaçait un champ signature dans le corps même. Il est toujours envoyé sans modification, les intégrations existantes continuent donc de fonctionner, mais il est obsolète. Le vérifier suppose de retirer le champ puis de reconstruire le reste du JSON sous forme de texte exactement comme PHP l’écrit, y compris son habitude d’écrire / sous la forme \/. Dans un autre langage, c’est presque impossible à réussir.

Développez les nouvelles intégrations autour de l’en-tête. Si vous vérifiez le champ aujourd’hui, rien ne casse : les deux sont envoyés à chaque livraison, vous pouvez donc basculer quand cela vous convient. Les deux valeurs ne sont jamais identiques, car elles couvrent des données différentes — ne les comparez jamais entre elles.

Conseils pour un traitement sécurisé

  • Attribuez à chaque webhook son propre secret et faites-le tourner régulièrement.
  • Utilisez une fonction de comparaison à temps constant (par exemple hash_equals en PHP ou crypto.timingSafeEqual en Node.js) pour prévenir les attaques temporelles.
  • Vérifiez la signature avant d’agir sur le contenu du payload.
  • Effectuez des contrôles 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.

Was this helpful?