Webhooks

Comment prévenir votre boutique ou votre ERP quand quelque chose change dans Bruxel, sans que personne n'ait à vérifier.

Ce tutoriel a une vidéo dans d'autres langues : en espagnol · en anglais

À quoi ils servent

Un webhook est une de vos adresses à laquelle Bruxel envoie un avis quand quelque chose arrive : une description est prête, une fiche a été publiée. Votre système réagit tout seul, au lieu que quelqu'un aille voir si c'est fait.

Quels événements écouter

En enregistrant l'adresse, vous choisissez ce dont vous voulez être informé. Seul ce que vous avez demandé est envoyé, et chaque avis identifie le produit et la langue concernés. `product.updated` part de tout changement réel de la fiche — y compris l'écriture d'une valeur d'attribut — et dit ce qui a changé (champs et codes, jamais les valeurs) : prenez-le comme un réveil et relisez la fiche, ou parcourez le flux des changements de l'API.

Signature et secret

Chaque avis est signé avec un secret qui vous est montré UNE seule fois, à l'enregistrement du webhook. Votre système utilise cette signature pour vérifier que l'avis vient bien de Bruxel et pas d'un tiers. Si vous le perdez, vous pouvez le renouveler : le précédent cesse aussitôt de fonctionner.

En cas d'échec

Si votre adresse ne répond pas, Bruxel réessaie. Chaque webhook affiche son dernier succès, sa dernière erreur et son nombre d'échecs consécutifs.

Après plusieurs échecs consécutifs, le webhook se désactive de lui-même. C'est volontaire : une destination morte que personne ne surveille accumule des tentatives indéfiniment. Une fois corrigée, réactivez-le depuis le même écran.

Livraisons et appels

Sur chaque webhook, «Voir les livraisons» ouvre la liste de chaque tentative d'envoi d'une notification : quand elle est partie, ce que votre adresse a répondu (ou pourquoi elle n'a pas répondu) et le temps que cela a pris. «Voir le détail» montre ce qui a été envoyé et ce qui a été répondu. Les administrateurs y ont accès.

Ce qui a été envoyé : la notification telle qu'elle est partie, avec ses en-têtes. La signature n'est jamais conservée.
Ce qui a été répondu : les 2 premiers Ko de la réponse de votre adresse.
Avant l'enregistrement, Bruxel masque tout ce qui ressemble à un identifiant (jetons, mots de passe, clés) et laisse une marque [•••] à sa place.

«Renvoyer» envoie de nouveau la même notification, signée à nouveau et avec le même X-Bruxel-Delivery. Votre système relit le produit tel qu'il est aujourd'hui : renvoyer ne répète donc pas un ancien changement. Ce n'est pas proposé si la notification est toujours dans la file (elle partira toute seule), si le webhook est en pause ou a été supprimé, ou si les 30 jours qu'elle reste dans la file sont passés.

Dans Clés API, «Voir les appels» ouvre ce que chaque clé a demandé ou écrit sur chaque produit via l'API publique. Pour une écriture, on conserve ce que votre système a envoyé et ce que Bruxel a répondu (pour un envoi en masse, celui des premiers produits) ; pour une lecture, seulement qui a appelé, quelle route et quel code. Les listes et les flux ne sont pas enregistrés.

Ce qui est envoyé et répondu est conservé 90 jours, jusqu'à 1 Go par organisation : quand c'est plein, les plus anciens partent d'abord. Les données de chaque livraison et de chaque appel durent jusqu’à 13 mois (avec beaucoup de trafic, on garde les 500 000 plus récentes de chaque type). Un administrateur peut désactiver l'enregistrement sur le même écran ; le désactiver ne supprime pas ce qui a déjà été conservé.

Détail technique

Le format exact de l'avis, la vérification de la signature pas à pas et des exemples dans plusieurs langages se trouvent dans le portail développeurs.