Les webhooks

Un webhook prévient une autre application quand une fiche change. Vous choisissez le type de fiche, les événements à suivre et l'adresse à appeler. À chaque événement, Docage envoie les données à cette adresse, suit la livraison et réessaie en cas d'échec.

Accéder aux webhooks

Dans le menu, ouvrez Organisation, puis Webhooks. Le module dépend de votre offre : une marque peut ne pas le proposer. Il regroupe Mes webhooks, Mes modèles de webhooks et le Journal des envois.

La liste Mes webhooks

La liste montre le Nom, le Type de fiche, les Événements, le Périmètre, l'URL, l'État et le Dernier envoi livré.

• Ouvrir une fiche : double-cliquez sur la ligne, ou cliquez sur le bouton Détails.
• Agir sur une ligne : ses boutons ouvrent le Journal des envois, Tester le webhook et la Constellation.
• Dupliquer, supprimer, exporter : cochez des lignes, puis utilisez les boutons de la barre.
• Récupérer un webhook supprimé : Afficher la corbeille propose Restaurer et Supprimer définitivement.

Créer un webhook

Cliquez sur le + de Mes webhooks dans le menu, qui déplie aussi vos modèles, ou choisissez Nouveau webhook dans le bouton flottant de la liste.

Renseignez les cartes de l'onglet Réglages, puis choisissez Enregistrer le webhook. Le type de fiche, au moins un événement et l'adresse sont obligatoires. Si vous laissez le nom vide, Docage le compose à partir du type, des événements et de l'adresse. Le secret de signature est généré à l'enregistrement. Les en-têtes personnalisés s'ajoutent ensuite.

Les réglages d'un webhook

Quoi : le type et les événements

Type de fiche propose les types de votre organisation. Une fois le webhook enregistré, le type ne change plus. Choisissez ensuite un ou plusieurs Événements.

Les messages et les publications de portail font exception : le webhook se pose sur une conversation, un portail ou leur modèle. Il ne part qu'à la création, sans champ surveillé ni filtre.

Surveiller un champ restreint un événement de modification ou de changement de statut. L'envoi ne part que si l'un des champs surveillés change. La valeur de départ et la valeur d'arrivée sont facultatives. Sans champ surveillé, toute modification part.

Pour quelles fiches : le périmètre et le filtre

Le Périmètre vaut Toutes les fiches du type, Les fiches issues d'un modèle ou Une fiche précise. Les deux derniers vous demandent de choisir le modèle ou la fiche.

Le filtre limite les envois selon les valeurs de la fiche. Si un critère ne peut pas être jugé, rien ne part, et le journal le dit.

Si plusieurs webhooks correspondent à un événement, chacun fait son envoi. Un webhook dont la fiche écoutée est supprimée définitivement part à la corbeille.

Où : l'adresse appelée et la charge

L'Adresse doit être en https://. Les adresses locales et privées sont refusées à l'enregistrement et à chaque envoi. Utilisez l'adresse définitive : une redirection compte comme un échec.

Le bouton Insérer un champ de la fiche ajoute à l'adresse un champ du type écouté.

La Charge utile vaut Complète (la fiche entière, telle que l'auteur du webhook la voit) ou Légère (ses identifiants et ce qui a changé). Une suppression part toujours en charge légère.

Format du corps indique la version. Un webhook resté en version 1 propose Passer au format 2 : prévenez le récepteur avant d'enregistrer.

Sécurité : signature, jeton, en-têtes

Chaque envoi est signé selon la norme Standard Webhooks. Le récepteur se sert du Secret de signature pour vérifier l'envoi. Révéler montre le secret et écrit une ligne d'historique. Copier le place dans le presse-papiers. Renouveler en génère un nouveau : l'ancien reste accepté 24 heures, le temps de mettre le récepteur à jour.

Le Jeton partagé sert au récepteur qui ne vérifie pas la signature. Activez l'interrupteur et enregistrez : le jeton est généré, puis envoyé à chaque appel. Renouveler un jeton invalide l'ancien tout de suite.

Ajouter un en-tête crée un en-tête personnalisé, 20 au plus. Une fois enregistrée, sa valeur reste masquée, sauf ses derniers caractères. Certains noms sont réservés, comme Authorization ou tout nom qui commence par webhook-.

État

L'interrupteur Actif coupe le webhook. Désactivé, il retient ses envois : rien n'est perdu. Une fois enregistré dans cet état, il se remet en service par Réactiver…. La carte affiche En service, le nombre d'échecs consécutifs, En panne depuis le… ou Désactivé.

Les envois sont composés avec les droits de l'auteur du webhook : il ne reçoit que ce que cet auteur voit. Un administrateur de l'organisation peut choisir Reprendre à mon nom ; ce bouton n'est proposé qu'à lui.

Les autres onglets de la fiche

Envois montre le journal de ce webhook. Historique garde les changements, les secrets révélés, les pannes et les réactivations. Constellation montre ce qui est lié au webhook, dont la fiche écoutée. Les onglets Flux liés et Droits complètent la fiche.

Tester un webhook

Choisissez Tester le webhook dans le bouton flottant de la fiche, ou sur la ligne de la liste. L'essai part comme un vrai envoi, signé, vers l'adresse du webhook.

1. Sous Avec quelles données ?, choisissez Un exemplaire vide du type ou Une fiche. Si l'adresse cite un champ, une fiche est obligatoire.
2. Cliquez sur Envoyer l'essai.

Le résultat s'affiche dans le bandeau, et l'envoi s'écrit au journal avec la mention Essai. Un essai raté n'est pas réessayé.

Quand un webhook tombe en panne

Chaque envoi a droit à dix tentatives sur quatre jours. Le webhook passe en panne après 72 heures d'échecs, ou dès que le récepteur répond 410. Son auteur et les administrateurs reçoivent une alerte dans la cloche et un email.

1. Corrigez la cause, par exemple l'adresse, et enregistrez.
2. Dans la carte État, cliquez sur Réactiver….
3. Gardez Rejouer les envois retenus pour les faire partir, ou coupez-le pour les annuler.
4. Cliquez sur Réactiver.

Les envois retenus partent vers l'adresse actuelle du webhook. Un envoi déjà en Échec, comme celui qui a reçu la réponse 410, le reste : rejouez-le depuis le journal.

Le journal des envois

Le Journal des envois réunit les envois de tous les webhooks que vous voyez. L'onglet Envois d'une fiche montre la même grille, pour ce seul webhook.

Chaque ligne donne la date, le Webhook, l'Événement, le Type de fiche, la Fiche, le Statut, les Tentatives, le code HTTP et la Raison d'un échec. Le nom du webhook et celui de la fiche ouvrent leur fiche.

Un envoi livré reste 30 jours au journal, les autres 90 jours.

Les gestes d'un envoi

• Détail de l'envoi, ou un double clic : le corps envoyé, les en-têtes, avec les secrets masqués, et chaque tentative avec sa raison.
• Rejouer le même envoi : le même corps et le même identifiant, tout de suite. Le récepteur peut ainsi reconnaître un doublon. Ce geste n'est pas proposé pour un envoi en attente ou en nouvel essai.
• Renvoyer avec la fiche actuelle : un envoi neuf, composé à partir de la fiche telle qu'elle est aujourd'hui.
• Rejouer la sélection : cochez des lignes. Les envois sont remis en attente et repartent peu après.

Un envoi part toujours vers l'adresse que porte le webhook au moment de la tentative.

Les modèles de webhooks

Un modèle garde des réglages à réutiliser. Il ne reçoit rien et n'a pas de secret : chaque webhook qui en est tiré reçoit le sien.

• Créer un modèle : cliquez sur le + de Mes modèles de webhooks, ou choisissez Nouveau modèle de webhook.
• Créer un webhook depuis un modèle : cliquez sur le bouton Nouveau webhook à partir du modèle de la ligne, ou passez par le + de Mes webhooks.

La fiche d'un modèle ajoute l'onglet Webhooks tirés du modèle. Son onglet Droits se coupe en deux : Droits du modèle et Droits des webhooks tirés du modèle.

L'onglet Webhooks d'une fiche

De nombreuses fiches portent un onglet Webhooks, qui liste les webhooks posés sur elles. Sur un modèle, il liste ceux posés sur ce modèle. Sur une fiche, il ne montre pas ceux de son modèle.

Nouveau webhook sur cette fiche ouvre un webhook déjà réglé : type de la fiche, périmètre sur cette fiche et, pour une fiche, événement Modification.

Un intégrateur peut aussi gérer ses webhooks par l'API.