Webhooks : envoyer ses commandes et recevoir les statuts

Un webhook, expliqué sans vocabulaire technique

Imaginez que vous attendiez de savoir si un colis est arrivé. Première méthode : vous appelez l'entrepôt toutes les dix minutes pour demander. Vous obtenez l'information, mais vous passez votre journée au téléphone et l'entrepôt passe la sienne à répondre « pas encore ». Deuxième méthode : vous laissez votre numéro, et l'entrepôt vous appelle quand le colis arrive. C'est exactement ce qu'est un webhook : vous laissez une adresse, l'autre système vous appelle quand il a quelque chose à dire.

Techniquement, l'« adresse » est une URL de votre site, et l'« appel » est une requête web contenant les informations de l'événement. C'est tout. Il n'y a aucune autre magie, et c'est pour cela qu'un webhook fonctionne avec n'importe quel langage et n'importe quel hébergement : si votre site sait recevoir un formulaire, il sait recevoir un webhook.

Deux conséquences découlent de cette simplicité, et elles expliquent le reste de cette page. La première : comme n'importe qui peut appeler une adresse, il faut un moyen de prouver que l'appel vient bien de qui il prétend — c'est la signature. La seconde : comme un appel peut échouer, il faut un moyen de le rejouer — ce sont les réessais.

Sens entrant : vos commandes arrivent chez nous

C'est la voie d'entrée des outils qui ne figurent dans aucune liste d'intégrations. Vous créez une connexion, la plateforme vous donne une adresse unique, et votre outil l'appelle à chaque commande. Le format attendu est le même que celui de l'API : nom du client, téléphone, ville, adresse, total à encaisser, articles avec leur SKU et leur quantité, et votre référence de commande.

Si votre outil envoie un format différent — et c'est fréquent avec un site maison ou un outil d'automatisation — la plateforme ne devine rien. Le premier envoi est conservé comme échantillon, elle vous propose de relier chacun de vos champs au champ correspondant, et les commandes reçues entre-temps sont rejouées dans l'ordre d'arrivée une fois la correspondance enregistrée. C'est le même mécanisme que pour une boutique connectée.

Une fois la commande lue, elle traverse les mêmes contrôles que tout le reste : téléphone normalisé, ville rapprochée, SKU vérifié, total comparé à la somme des prix. Une commande incomplète devient un lead endommagé plutôt que d'être refusée. Et une commande déjà reçue, parce que votre outil a réessayé, ne crée pas de second lead : son identifiant est mémorisé par connexion.

Sens sortant : les étapes de la commande arrivent chez vous

Dans l'autre direction, vous enregistrez l'adresse de votre système et vous choisissez ce que vous voulez apprendre. À chaque fois qu'une de vos commandes franchit une étape, votre adresse est appelée avec le détail de la commande : sa référence, la vôtre, le client, le total, le profit vendeur, les statuts et le numéro de suivi quand il existe.

La signature, et pourquoi une adresse secrète ne suffit pas

Le raisonnement naturel est de se dire qu'une adresse que personne ne connaît fait office de mot de passe. C'est faux, pour une raison simple : une adresse circule. Elle apparaît dans un journal de serveur, dans une capture d'écran, dans un message à un prestataire, dans l'historique d'un outil d'automatisation. Quiconque l'a vue peut envoyer un faux « colis livré » à votre système, et votre comptabilité le croira.

La signature règle cela. À chaque envoi, l'expéditeur calcule une empreinte du contenu avec un secret connu des deux seuls côtés, et la place dans un en-tête. Le destinataire recalcule la même empreinte de son côté et compare. Comme le secret ne circule jamais, personne ne peut fabriquer une empreinte valable — même en connaissant l'adresse, même en connaissant le contenu exact à imiter.

Les envois sortants de la plateforme sont signés sur l'horodatage et le corps brut réunis, et l'horodatage est transmis dans son propre en-tête. Cette double information vous permet de refuser deux choses différentes : un contenu modifié, parce que l'empreinte ne correspondra plus, et un contenu authentique mais rejoué des heures plus tard, parce que l'horodatage sera trop ancien. Le secret ne s'affiche qu'une seule fois, au moment où l'adresse est créée.

Dans le sens entrant, le même principe s'applique en miroir : vous choisissez un secret, vous le mettez des deux côtés, et vous signez le corps de vos envois. Si vous ne mettez pas de secret, l'adresse secrète reste votre seule protection — ce qui est acceptable pour un début, et insuffisant dès que l'adresse a été partagée une fois.

Échecs, réessais et désactivation

Les envois sortants ne partent pas pendant la requête qui produit l'événement. C'est un choix important : votre serveur peut être lent, éteint ou derrière un pare-feu, et la confirmation d'une commande par un agent ne doit ni attendre ni échouer à cause de cela. Les événements sont donc mis en file, puis envoyés séparément.

Un envoi est réussi quand votre serveur répond un code de succès. Sinon, il est réessayé plus tard, avec des intervalles de plus en plus espacés, pendant quelques heures. Un serveur éteint une nuit retrouve donc ses événements au matin, sans avoir été appelé mille fois entre-temps. Passé un certain nombre de tentatives, l'envoi est abandonné et consigné comme échec.

Si votre adresse échoue de façon répétée sur une longue série d'envois, elle est désactivée automatiquement : un serveur définitivement disparu ne doit pas être appelé indéfiniment. Elle se réactive d'un clic une fois votre serveur réparé. Entre-temps, la liste des derniers envois montre ce qui est parti, ce qui a échoué, et avec quel code de réponse — c'est elle qui répond à la question « pourquoi mon système n'a rien reçu ».

• Répondre vite — Enregistrez l'événement, répondez un succès, traitez ensuite. Traiter avant de répondre finit par dépasser le délai d'attente.
• Accepter les répétitions — Un même événement peut arriver deux fois si votre réponse s'est perdue en route. Votre code doit pouvoir le recevoir deux fois sans conséquence.
• Refuser le reste — Signature invalide, horodatage ancien, événement inconnu : répondez une erreur et ne traitez rien.
• Une adresse publique en HTTPS — Une adresse locale ou privée est refusée à l'enregistrement : elle ferait appeler une machine qui n'est pas la vôtre.

Quand préférer un webhook à une boutique connectée

Si une intégration officielle existe pour votre boutique, utilisez-la : elle s'abonne seule, gère le renouvellement des accès et dispose d'une relecture de secours en cas de notification perdue. Un webhook que vous construisez vous-même n'a pas ce filet, sauf si vous l'écrivez.

• Votre outil n'a pas d'intégration — C'est le cas typique : un site maison, un tunnel de vente, un outil de gestion interne. Le webhook est la voie la plus directe.
• Vous passez par un outil d'automatisation — Un connecteur intermédiaire sait déclencher sur « nouvelle commande » et envoyer une requête : vous n'écrivez pas une ligne de code.
• Vous voulez être prévenu des statuts — C'est le seul moyen d'apprendre une livraison sans interroger l'API en boucle, et il n'a pas d'équivalent du côté des boutiques connectées.
• Vous avez besoin de lire autre chose — Un webhook annonce un événement ; il ne permet pas d'interroger le catalogue, les villes ou l'historique. Pour cela, c'est l'API qu'il faut.