Que sont les webhooks et comment les configurer dans Sendcloud? – Sendcloud Help Center

Objectif: apprendre les bases des webhooks et comment les configurer dans votre compte Sendcloud.

Pour utiliser les webhooks, vous devez vous connecter à Sendcloud via l'API. Pour plus d'informations sur la connexion avec notre API, nous vous renvoyons à notre documentation API.

Pour plus d'informations sur les webhooks Sendcloud, vous pouvez consulter les sections Webhooks de notre documentation API.

Pour le support des webhooks spécifique à l'intégration, consultez notre article : Amélioration de la sécurité et du support d'intégration des webhooks. Il couvre la configuration des webhooks pour différentes intégrations et les meilleures pratiques pour sécuriser vos webhooks.

Que sont les webhooks?

Les webhooks permettent aux applications de communiquer entre elles en "temps réel". Elles peuvent aussi communiquer en passant par une API. Contrairement à une API qui fonctionne par polling, un webhook reçoit des données dès que l'application les traite. Il n'est pas nécessaire de faire une demande car il s'agit d'un processus automatique. Vous n'avez donc pas à vous soucier du retard de communication.

API: une API extrait de manière temporaire les données de l'application en faisant une demande.

Webhook: un webhook ne tire pas de données mais reçoit des données envoyées par l'application dès qu'elles arrivent.

Exemple: recevoir des mises à jour de suivi de Sendcloud

(Voir l'image ci-dessous)

Lorsque vous recevez la mise à jour du suivi via l'API, voici ce qu'il se passe:
Votre application essaie d'extraire les données de suivi de Sendcloud. Elle le fera même si aucune nouvelle donnée n'est disponible.
Lorsque vous voulez recevoir des mises à jour de suivi via un webhook, voici ce qu'il se passe:
Sendcloud envoie les mises à jour de suivi vers votre application dès qu'elles sont disponibles dans Sendcloud.

Les webhooks Sendcloud

Webhook Integration Object: ce webhook entre en jeu lorsqu'une nouvelle intégration API est ajoutée à Sendcloud. Il se déclenche lorsqu'une intégration API est connectée, supprimée ou mise à jour. Cliquez ici pour voir ce que contient ce webhook.

Webhook Parcel Status Changed Object: ce webhook entre en jeu lorsqu'un colis change de statut, quel que soit le changement de statut. Cliquez ici pour voir ce que contient ce webhook.

Webhook Return Created Object: Ce webhook est déclenché lorsqu'un retour est créé via l'API ou le Portail de retour. Cliquez ici pour consulter les détails du payload.

Comment configurer les webhooks dans Sendcloud?

Pour que Sendcloud communique les mises à jour des colis (comme celles de suivi), vous devez créer un endpoint API. Chaque fois qu'une mise à jour se produit, Sendcloud fera une demande via cet endpoint. Pour plus d'informations, consultez la section Webhooks dans notre documentation API.

Copiez l'url du webhook de votre application où vous le souhaitez
Allez dans votre compte Sendcloud et ouvrez vos paramètres de votre boutique en ligne en allant dans Réglages > Boutiques connectées > Modifier.
Cochez la case Webhook feedback enabled
Trouvez le champ Webhook url (voir l'image ci-dessous) et collez-y votre url de webhook.
Testez votre webhook en cliquant sur Test API webhook
Cliquez sur Enregistrer

C'est fait ! Votre webhook est maintenant configuré et les données devraient commencer à arriver dans votre application. Vous pouvez l'utiliser pour mettre en place des déclencheurs qui mènent à certaines actions. Par exemple, vous pouvez connecter vos e-mails de suivi aux mises à jour de suivi . Vous pourrez alors donner des mises à jour instantanées à vos clients.

Pour les retours, vous recevrez des mises à jour par webhook uniquement si l'envoi a été créé via l'API.

FAQ

Si je configure un webhook, à quels colis s’applique-t-il ?

Les webhooks sont configurés par intégration. Cela signifie que le webhook s’appliquera uniquement aux colis créés via l’intégration pour laquelle le webhook a été configuré. Les colis créés via d’autres intégrations ou méthodes ne déclencheront pas ce webhook.

Pourquoi mon URL de webhook renvoie-t-elle une erreur 404 ou est-elle inaccessible ?

Problème : L’URL du webhook est incorrecte (erreur de saisie, mauvais domaine ou HTTPS manquant) ou le point de terminaison n’est pas accessible publiquement.

Exemples:

404 Not Found

DNS resolution failed

Solution : Vérifiez soigneusement la syntaxe de l’URL et le domaine. Assurez-vous que le point de terminaison est accessible publiquement et utilise le protocole HTTPS avec un certificat SSL/TLS valide.

Pourquoi ai-je des erreurs de certificat SSL/TLS avec mon webhook ?

Problème : Le point de terminaison utilise un certificat expiré, auto-signé ou mal configuré.

Exemples:

SSL Handshake failed

Unable to verify certificate

Solution : Installez un certificat SSL valide provenant d’une autorité de certification (CA) de confiance, renouvelez les certificats expirés et vérifiez que les certificats intermédiaires sont correctement installés.

Pourquoi mes requêtes de webhook expirent-elles ou ne répondent-elles pas ?

Problème : Le serveur qui reçoit le webhook est trop lent ou ne répond pas du tout.

Exemples:

 Request timed out

 Connection reset

Solution : Assurez-vous que le serveur répond dans le délai imparti, optimisez le code pour un traitement plus rapide, ou déplacez les tâches lourdes vers des processus en arrière-plan. Vérifiez également les pare-feu ou les limitations de débit (rate limiting).

Pourquoi mon webhook renvoie-t-il des erreurs HTTP telles que 405 ou 500 ?

Problème : Le point de terminaison attend une méthode HTTP spécifique ou ne renvoie pas de réponse correcte.

Exemples:

405 Method Not Allowed

500 Internal Server Error

Solution : Assurez-vous que le point de terminaison accepte les requêtes POST, renvoyez un code de statut 2xx en cas de réception réussie et gérez les erreurs correctement à l’aide de logs.

Pourquoi l’authentification ou la vérification de la signature de mon webhook échoue-t-elle ?

Problème : Le fournisseur du webhook signe les requêtes, mais le point de terminaison ne les vérifie pas correctement ou utilise de mauvaises clés.

Exemples:

401 Unauthorized

403 Forbidden

Solution : Mettez en place une vérification HMAC ou de signature à l’aide de la clé secrète correcte. Assurez-vous que les en-têtes et le contenu (payload) sont analysés exactement comme ils ont été envoyés.

Pourquoi le contenu (payload) de mon webhook est-il invalide ou mal formé ?

Problème : Le webhook envoie des données au format JSON (ou autre), mais le serveur récepteur ne peut pas les interpréter correctement.

Exemples:

400 Bad Request

Unexpected token in logs

Solution : Vérifiez que le type de contenu (Content-Type) est pris en charge (généralement application/json), validez et enregistrez le payload, et mettez à jour le code du point de terminaison pour accepter les nouveaux champs ou formats.

Pourquoi certaines requêtes de webhook sont-elles limitées ou ignorées ?

Problème : Le point de terminaison reçoit trop de requêtes et commence à en refuser certaines.

Exemples:

429 Too Many Requests

Requests delayed or silently failing

Solution : Ajoutez une file d’attente ou une limitation de débit (throttling) pour gérer les pics de charge, implémentez des tentatives automatiques (retries) avec backoff exponentiel et surveillez les ressources du serveur pour les ajuster si nécessaire.

Cliquez ici pour accéder à notre référence API Sendcloud et l'utilité du webhook.