Configurer des webhooks

Avec une clé API, c'est un autre programme qui récupère vos données quand il en a besoin. Avec un webhook, c'est l'inverse : nous envoyons un message vers une adresse à vous dès qu'il se passe quelque chose.

Cela évite d'attendre. Une commande qui arrive à huit heures quinze est dans votre comptabilité à huit heures quinze — et pas au tour suivant, une heure plus tard.

Ce que nos clients en font :

• chaque vente immédiatement dans la comptabilité ou dans une base de données maison ;
• un petit écran à l'entrée qui montre qui vient d'entrer ;
• un message dans une conversation de groupe dès qu'une visite est complète ;
• un e-mail ou un sms maison vers l'acheteur, en plus du nôtre.

Cet article est le mode d'emploi de l'écran, pas à pas. Si vous voulez d'abord savoir ce qu'est un webhook et si vous en avez besoin, lisez Webhooks.

Bon à savoir : les webhooks font partie de la même formule que l'API. Si vous êtes sur une formule plus petite, Accès API ne figure pas dans votre menu ; si vous arrivez quand même sur l'écran, vous voyez des explications et un bouton Vers l'abonnement.

Où aller

Ouvrez dans le menu de gauche Paramètres → Accès API et cliquez en haut sur l'onglet Webhooks. Seul le rôle Propriétaire voit cet écran.

Vous voyez trois blocs : C'est nous qui vous appelons (explications), Nouvelle destination (le formulaire) et Destinations (ce qui existe déjà).

Ce dont vous avez besoin

Une seule chose, et elle doit exister avant de commencer : une adresse sur votre propre serveur capable de recevoir des messages. C'est un petit travail de programmation de votre côté — votre développeur ou votre logiciel de comptabilité comprendra si vous dites « un endpoint pour les webhooks ».

Trois exigences :

1. Ce doit être du https. Nous refusons une adresse http ordinaire : des données d'acheteurs passent sur cette ligne.
2. Elle doit être joignable depuis l'extérieur. Une adresse à l'intérieur de votre réseau de bureau (quelque chose en 192.168. ou 10.) nous ne pouvons pas l'atteindre, et nous la refusons.
3. Elle doit répondre vite. Nous attendons dix secondes. Si le traitement prend plus longtemps, faites répondre « ok » tout de suite et travaillez ensuite.

Ajouter une destination

Étape 1. Indiquez l'adresse. Dans le premier champ (https://...), l'adresse complète vers laquelle nous pouvons envoyer, par exemple https://comptabilite.monentreprise.be/webhooks/tickets.

Étape 2. Dites à quoi elle sert. Le deuxième champ (À quoi sert-elle ?) n'est pas obligatoire, mais pratique. « Notre comptabilité », « écran à la caisse ». Si vous en avez trois, vous saurez laquelle sert à quoi.

Étape 3. Cochez ce sur quoi nous pouvons vous prévenir. La liste se trouve sous Sur quoi devons-nous vous prévenir ?. C'est le choix le plus important. Ne cochez que ce que vous traitez vraiment : chaque message inutilisé est du travail pour votre serveur et du bruit dans votre journal. Au moins une case doit être cochée ; une destination sans messages ne recevrait jamais rien.

Message	Quand il part
Commande créée	Une commande est née (un panier ne compte pas).
Commande payée	L'argent est arrivé.
Commande annulée	La commande est annulée ou expirée.
Commande remboursée	Un remboursement total ou partiel a eu lieu.
Billet créé	Un billet a été émis.
Billet scanné	Il y a eu un scan à l'entrée — même s'il a été refusé.
Billet annulé	Un billet est annulé ou remboursé.
Créneau complet	Un créneau est plein.
Créneau à nouveau libre	Il y a de nouveau de la place dans un créneau complet.
Chèque-cadeau émis	Un bon cadeau a été vendu.
Chèque-cadeau utilisé	Un montant a été déduit d'un bon cadeau.
Abonnement émis	Un abonnement annuel a été créé.
Session de caisse clôturée	Un tiroir-caisse a été compté et fermé.
Facture émise	Une facture ou une note de crédit a été faite pour un acheteur.

Étape 4 (facultative). Destination de test. Si l'adresse pointe vers un environnement de test, cochez Destination de test (ne reçoit que des événements de test). Plus de détails sous « Une destination de test » ci-dessous.

Étape 5. Cliquez sur Ajouter une destination.

Vous pouvez avoir jusqu'à vingt destinations. Si vous en avez déjà vingt, supprimez-en d'abord une.

Le secret n'apparaît qu'une fois

Juste après apparaît un secret : une longue suite qui commence par whsec_.

Copiez-le maintenant et transmettez-le à celui qui construit la connexion. Si vous rafraîchissez la page ou changez d'onglet, il a disparu.

Avec ce secret, nous signons chaque message envoyé vers votre adresse. Votre serveur peut ainsi vérifier que le message vient bien de nous et pas de quelqu'un qui a intercepté votre adresse. Ce n'est pas un luxe : sans cette vérification, votre endpoint est une porte ouverte où n'importe qui peut glisser des commandes.

Vous avez perdu le secret ? Cliquez sur Nouveau secret. Vous en recevez un nouveau immédiatement et l'ancien cesse aussitôt de fonctionner — n'oubliez donc pas de le remplacer aussi de l'autre côté.

Pour celui qui construit la connexion, le portail développeurs explique précisément comment recalculer cette signature, avec des exemples en PHP, JavaScript et Python. Via l'API, il peut aussi demander un message d'exemple signé pour tester son propre code, sans devoir d'abord faire une vente.

Tester sans vente

Cliquez à côté d'une destination sur Message de test. Nous envoyons alors un seul message de type test.ping — pas de vraies données, juste un signal.

En dessous s'ouvre aussitôt le journal des messages, pour que vous voyiez ce que votre serveur a répondu. S'il indique Arrivé, cela fonctionne. S'il indique un code d'erreur, vous savez où chercher. Un message de test part aussi vers une destination désactivée.

Le journal des messages

Cliquez à côté d'une destination sur Messages. Vous voyez les cinquante derniers messages, et pour chacun :

• de quel type il s'agissait et quand il est parti ;
• ce que votre serveur a renvoyé (le nombre est le statut http ; 200 veut dire « ok ») ;
• combien de fois nous avons essayé ;
• où il en est : Arrivé, En route (nous essayons encore) ou Non livré.

Si un message n'est pas arrivé, vous pouvez le proposer à nouveau avec Réessayer. Pratique après avoir résolu une panne de votre côté.

Les messages restent trente jours. Ensuite ils sont nettoyés : le journal sert à trouver un problème, pas d'archive.

Ce qui se passe si votre serveur ne répond pas

Nous n'abandonnons pas tout de suite. Si un message n'arrive pas, nous réessayons six fois, avec des intervalles de plus en plus longs : après une minute, cinq minutes, une demi-heure, deux heures, douze heures et un jour. Ensemble, plus d'une journée et demie.

Si cela ne marche toujours pas :

• la destination reçoit la marque N'arrive pas ;
• vous recevez un e-mail. Il part vers l'E-mail de contact de votre organisation, ou vers l'Adresse de facturation (e-mail) si le premier est vide (tous deux sous Paramètres → Organisation, onglet Contact) ;
• la destination reste active. Les événements suivants sont à nouveau proposés, et dès que quelque chose arrive, la marque disparaît.

Vous recevez au plus un tel e-mail par jour et par destination. Un serveur hors service tout un week-end ne produit donc pas cent e-mails.

Une destination de test

Cochez Destination de test lors de la création lorsque l'adresse pointe vers un environnement de test. Une telle destination ne reçoit que des événements de test — ce qui arrive aux commandes de test d'une clé de test — et jamais de vraies ventes. Elle porte la marque Test dans la liste. Inversement, une destination ordinaire ne reçoit jamais rien d'une commande de test.

Cette séparation est stricte, et c'est voulu : un serveur de test qui traite par erreur une vraie commande envoie une confirmation à un vrai acheteur.

Désactiver ou supprimer

Désactiver arrête les livraisons mais conserve la destination, avec son secret et son journal ; elle porte la marque Désactivé. Pratique pendant une maintenance de votre côté. Cliquez à nouveau sur Activer et tout repart.

Supprimer enlève la destination et son journal. C'est irréversible ; une nouvelle destination reçoit un nouveau secret.

Il y a un troisième cas : si votre serveur répond un jour avec le code 410, nous désactivons la destination nous-mêmes. Ce code signifie littéralement « cette adresse n'existe plus », et continuer à frapper serait impoli. Il en va de même lorsque l'adresse pointe entre-temps vers un réseau interne. Cliquez sur Activer dès que c'est réglé.

Trois conseils pour celui qui construit la connexion

1. Répondez d'abord, traitez ensuite. Dites « ok » tout de suite et faites le vrai travail en arrière-plan. Sinon vous butez sur nos dix secondes.
2. Traitez de façon idempotente. Chaque message porte son propre numéro (l'Idempotency-Key). Si le même numéro arrive deux fois, ne faites rien. Nous réessayons en cas de doute, et une double réservation est pire qu'une double ligne de journal.
3. Ne comptez pas sur l'ordre. Deux messages peuvent se doubler lorsque le premier est répété. Regardez l'heure dans le message et son contenu, pas l'ordre d'arrivée.

Pour aller plus loin

• Webhooks — ce qu'est un webhook et quand vous en avez besoin, sans termes techniques.
• Créer une clé API — l'autre onglet de cet écran.
• Le portail développeurs — pour celui qui construit la connexion.