URL de webhook de notification

Le type de document URL de webhook de notification permet d'envoyer des notifications de documents vers un service de messagerie externe à l'aide d'une URL de webhook entrante. Les services pris en charge sont : Google Chat, Matrix (Hookshot), Mattermost, Rocket.Chat, Slack, Teams, Discord, Ntfy et Raven.

Prérequis

• Avoir les droits de création sur le type de document URL de webhook de notification.
• Pour envoyer un message de test depuis le formulaire, avoir le rôle Responsable système.
• Disposer de l'URL de webhook entrant fournie par le service concerné (par exemple un webhook de canal Slack ou un connecteur entrant Teams).

Créer une URL de webhook de notification

1. Ouvrez la liste URL de webhook de notification (espace de travail Intégrations, ou recherche Ctrl+K).
2. Renseignez les champs suivants :
   • Nom : nom du webhook, obligatoire ;
   • Service : service destinataire, obligatoire. « Slack » est proposé par défaut. Les services disponibles sont : Google Chat, Matrix (Hookshot), Mattermost, Rocket.Chat, Slack, Teams, Discord, Ntfy et Raven ;
   • URL du webhook : obligatoire. Les espaces situées en début et en fin d'URL sont supprimées à l'enregistrement. L'URL doit être une URL http ou https valide et comporter un hôte, sinon l'enregistrement est refusé ;
   • Afficher le lien vers le document : cochée par défaut. Lorsqu'elle est cochée, un lien vers le document concerné est ajouté au message envoyé.
3. Enregistrez le document.

Envoyer un message de test

Sur le formulaire d'un webhook enregistré, le bouton Envoyer un message de test, réservé aux responsables système, ouvre une boîte de dialogue :

• Message : texte à envoyer, « Message de test » par défaut, obligatoire ;
• Type de document de référence : type de document de référence, pré-rempli avec le type de document courant, obligatoire ;
• Nom de la référence : nom du document de référence, pré-rempli avec le nom du document courant, obligatoire.

Un envoi réussi affiche le message « Message de test envoyé ». Si le service refuse le message, l'erreur correspondante est affichée.

Configurer une notification avec le canal Webhook

1. Créez ou ouvrez une Notification.
2. Dans le champ Canal, sélectionnez Webhook.
3. Renseignez le champ URL de webhook de notification : il est obligatoire pour ce canal et fait le lien avec le webhook créé précédemment.
4. Saisissez le Sujet, obligatoire si aucun modèle d'e-mail n'est sélectionné, et le Message. Pour le canal Webhook, le type de message est automatiquement Markdown et n'est pas modifiable.
5. Aucun destinataire n'est à renseigner : la section Destinataires est masquée pour ce canal, l'envoi s'effectue via le webhook.
6. Enregistrez la notification.

Au déclenchement de la notification, le message est rendu puis envoyé au service configuré. Les messages rédigés avec l'éditeur de blocs (Block Editor) sont pris en charge. Si l'option Afficher le lien vers le document est cochée, le message comporte un lien vers le document concerné.

Comportement selon les services

• Slack : le message est envoyé dans le champ text ; l'option de lien ajoute un bouton « Voir le document ».
• Teams : le message est mis en forme sous forme de carte adaptative (Adaptive Card).
• Discord et Raven : le message est tronqué à 2 000 caractères si nécessaire, une entrée est alors ajoutée au journal des erreurs. L'avatar et le nom d'expéditeur utilisés sont ceux de l'application.
• Ntfy : le message est envoyé en texte brut ; lorsque l'option de lien est cochée, l'en-tête Click de la requête pointe vers le document.
• Matrix (Hookshot) : le lien vers le document est ajouté au message en syntaxe Markdown.
• Google Chat, Mattermost et Rocket.Chat : le message est envoyé en texte simple, avec le lien vers le document selon l'option cochée.

Erreurs d'envoi

Si le service est injoignable ou répond par une erreur, l'envoi échoue et un détail est consigné dans le Journal des Erreurs sous le titre « Impossible d'envoyer la notification par webhook. ». Pour Slack, les causes usuelles sont précisées (canal introuvable, canal archivé, action interdite, service indisponible).

Migration des configurations existantes

À la mise à jour, les configurations existantes sont migrées automatiquement :

• le type de document « Incoming Webhook URL » (anciennement « Slack Webhook URL ») est renommé en « Notification Webhook URL » ;
• le canal « External Collaboration Tool » des notifications devient « Webhook » ;
• le champ incoming_webhook_url (ou slack_webhook_url) de la notification devient notification_webhook_url ;
• l'option add_document_link du webhook devient show_document_link.

Les notifications exportées ou importées depuis d'anciennes versions (canal « Slack » ou « External Collaboration Tool », champs slack_webhook_url ou incoming_webhook_url) sont automatiquement converties à l'importation.