Webhooks : prévenez vos autres outils en temps réel

#Ce qu'est un webhook

Voyez cela comme votre projet qui appelle un autre service pour lui dire ce qui vient de se passer. Vous donnez à Briks une adresse (une URL fournie par l'autre outil), vous choisissez les événements à signaler, et chaque fois que l'un d'eux se produit, Briks envoie un message à cette adresse. De nombreux outils d'automatisation, outils de gestion de clients et modules complémentaires de tableur peuvent vous fournir une telle adresse.

Techniquement, chaque message est une requête POST : un appel qui porte un corps, ici écrit en JSON, un format de texte simple que les programmes savent lire. L'outil qui le reçoit lit ce corps et fait ce que vous avez configuré.

record.changed suit les modifications faites dans le studio : un enregistrement ajouté, modifié ou supprimé dans l'onglet Database, une collection vidée, ou la base de données restaurée. Les enregistrements que le site en ligne sauvegarde de lui-même, comme une demande de réservation envoyée par un visiteur, ne le déclenchent pas.

form.received est envoyé pour les entrées venant de l'aperçu comme de la production. Chaque message indique laquelle, afin que l'autre outil puisse ignorer les entrées de l'aperçu.

#Limites de chaque plan

Quand les appels du jour sont épuisés, un envoi n'est pas effectué et est marqué Failed avec : Today's calls for this project are used up, so this delivery was not sent. Send it again tomorrow.

Quand un projet a autant de webhooks que son forfait le permet, Add webhook est grisé et un lien Get more à côté du compteur ouvre la fenêtre de mise à niveau, qui nomme le plus petit forfait offrant de la place pour un autre.

#Ajouter un webhook

Chaque webhook de la liste affiche son adresse, sa note et ses événements, le secret avec lequel il est signé (les premiers caractères) et le déroulement de la dernière livraison. Son interrupteur le passe sur On ou Off, et ses trois points contiennent Send a test event (jusqu'à dix par heure, uniquement lorsqu'il est activé), Change, New signing secret et Delete.

#À quoi ressemble une livraison

Chaque envoi comporte les trois mêmes parties : type (le code de l'événement), timestamp (le moment où il s'est produit, en UTC) et data (les détails). Voici une saisie de formulaire :

Chaque envoi comporte aussi trois en-têtes : webhook-id (l'identifiant du message), webhook-timestamp (le moment de l'envoi, en secondes) et webhook-signature. Ils suivent le format ouvert Standard Webhooks, donc les outils qui le comprennent peuvent vérifier les envois à votre place.

#Vérifier qu'une livraison est authentique

N'importe qui peut envoyer un message à une adresse, donc le destinataire doit vérifier la signature avant de lui faire confiance. La signature est produite avec le secret de signature que vous seul et Briks possédez. Dès qu'un projet a un webhook, la page Webhooks affiche un court exemple de code sous Checking a delivery is genuine. En clair, la vérification se déroule ainsi :

1. Prenez le corps de la requête tel qu'il est arrivé, sous forme de texte, avant de le lire comme du JSON.
2. Reliez le webhook-id, le webhook-timestamp et le corps par des points.
3. Prenez votre secret, retirez le whsec_ du début et décodez le reste depuis le base64. C'est la clé.
4. Signez le texte assemblé avec HMAC SHA-256 et cette clé, écrivez le résultat en base64, et placez v1, devant.
5. La livraison est authentique si cela correspond à l'une des valeurs séparées par des espaces dans webhook-signature, et si l'horodatage date de moins de cinq minutes.

Une livraison renvoyée conserve son webhook-id, ce qui permet au destinataire de garder les identifiants déjà traités et d'ignorer les doublons.

#Envois et nouvelles tentatives

Deliveries liste chaque envoi des trente derniers jours, du plus récent au plus ancien. Affinez avec Status puis appuyez sur Show. Cliquez sur un envoi pour voir le message complet, l'erreur éventuelle et la réponse de l'adresse.

Chaque essai attend une réponse pendant 15 secondes au maximum. Si la réponse n'est pas un 2xx, Briks réessaie : cinq essais en tout, le premier tout de suite, puis après environ 30 secondes, 2 minutes, 8 minutes et 32 minutes, soit environ 45 minutes du premier au dernier. Une réponse 410 (gone) arrête immédiatement les nouvelles tentatives. Les redirections ne sont pas suivies, donnez donc l'adresse finale.

Une fois qu'une livraison est Failed ou Delivered, Send again renvoie le même message avec le même identifiant, signé à nouveau. Le webhook doit être activé.

#Analyses et paramètres

Insights résume les trente derniers jours : Deliveries, la part Delivered, Failed after every try (avec le nombre de nouvelles tentatives nécessaires) et le temps d'Average answer. En dessous, By event et By address montrent où se concentrent les échecs.

Settings propose Download JSON sous Download the webhooks, avec l'adresse, les événements et la note de chaque webhook. Les secrets de signature ne sont jamais inclus. Sa zone de danger contient Clear log, qui supprime le journal des envois et arrête toute nouvelle tentative, et Delete all, qui supprime tous les webhooks après que vous avez saisi le nom du projet. Les deux sont réservés aux Owners et aux Admins.

#Exemple concret : envoyer les réponses d'un formulaire vers un autre outil

Les envois de formulaire ne peuvent pas être exportés depuis le studio : un webhook permet donc de les conserver dans un autre outil à mesure qu'ils arrivent. Le studio les garde aussi : les 100 derniers s'affichent sous Settings, Forms.