Wiki

Webhooks

Notifications sortantes par dépôt (Discord, Slack, Teams, custom) sur check-in, check-out et résumés d'activité. Création, format des messages, variables de template, garde SSRF.

Introduction

Un webhook envoie une notification sortante vers un service externe (Discord, Slack, Microsoft Teams, ou une URL de votre choix) chaque fois qu'un événement se produit dans un dépôt : un check-in, un check-out, ou un résumé d'activité périodique. C'est le moyen le plus simple de tenir une équipe au courant sans qu'elle ouvre le client : un message tombe dans votre canal quand quelqu'un soumet du travail.

Les webhooks sont configurés par dépôt, dans le panneau d'administration du client desktop, onglet Webhooks. Un dépôt peut avoir plusieurs webhooks (par exemple un vers Discord pour toute l'équipe, un vers un Slack privé pour les leads).

Accès et rôles

La gestion des webhooks est réservée aux administrateurs du dépôt : un super admin (rôle admin) sur n'importe quel dépôt, ou un project_admin sur les dépôts qu'il administre. Les autres rôles ne voient pas cet onglet.

À savoir L'onglet Webhooks utilise le système multi-webhooks (plusieurs entrées par dépôt). Une ancienne notification Discord à URL unique existe encore côté serveur pour compatibilité, mais elle n'est pas exposée dans ce nouvel onglet : utilisez les webhooks décrits ici.

Créer un webhook

Le formulaire Add Webhook : Name, URL, Type (discord/slack/teams/custom), cases Events, interrupteur Enabled.

Ouvrez le panneau d'administration, sélectionnez le dépôt, puis l'onglet Webhooks.
Cliquez sur Add Webhook.
Renseignez les champs, puis Create.

Champ	Valeur
Name	Un libellé pour vous y retrouver (ex. `Discord équipe`). Requis.
URL	L'URL du webhook fournie par le service cible. Requise. Voir Sécurité pour les URLs refusées.
Type	`discord`, `slack`, `teams` ou `custom`.
Events	Un ou plusieurs parmi `checkin`, `checkout`, `activity_summary`. Au moins un est obligatoire.
Enabled	Interrupteur d'activation (visible à l'édition, et depuis la liste).

Pour obtenir l'URL côté Discord : Paramètres du salon → Intégrations → Webhooks → Nouveau webhook → Copier l'URL. Côté Slack : créez une Incoming Webhook dans les réglages de l'application Slack. Côté Teams : Connecteurs → Incoming Webhook sur le canal.

Tutoriel : webhook Discord

C'est le cas le plus courant. La partie « obtenir l'URL » se passe entièrement dans Discord, une seule fois.

Côté Discord : obtenir l'URL

Ouvrez Discord et allez sur votre serveur. Choisissez (ou créez) le salon texte qui recevra les notifications, par exemple #uversion.
Passez la souris sur le nom du salon et cliquez sur l'icône roue dentée (« Modifier le salon »).
Dans le menu de gauche, ouvrez l'onglet Intégrations.
Cliquez sur Webhooks, puis sur Nouveau webhook. Discord en crée un automatiquement, rattaché à ce salon.
Cliquez sur le webhook créé pour l'ouvrir. Donnez-lui un nom (par exemple uVersion), et vérifiez que le salon cible est le bon. Une image d'avatar est facultative.
Cliquez sur Copier l'URL du webhook. L'URL ressemble à https://discord.com/api/webhooks/123456789/AbCdEf....

Gardez cette URL secrète Toute personne qui possède l'URL peut poster des messages dans votre salon. Ne la commitez pas dans le dépôt et ne la partagez pas publiquement. Si elle fuite, supprimez le webhook côté Discord et recréez-en un.

Côté uVersion : brancher l'URL

Dans le client desktop, ouvrez le panneau d'administration, sélectionnez le dépôt, puis l'onglet Webhooks.
Cliquez sur Add Webhook.
Name : un libellé pour vous (ex. Discord équipe).
URL : collez l'URL copiée depuis Discord.
Type : choisissez discord (indispensable pour que le message soit mis en forme en embed Discord).
Events : cochez les événements voulus, par exemple checkin.
Cliquez sur Create.
Sur la ligne du webhook, cliquez sur Send test : un message de test doit apparaître dans le salon Discord en quelques secondes.

Si le test échoue avec un code HTTP 401 ou 404, l'URL est mauvaise ou le webhook a été supprimé côté Discord : recopiez l'URL. Si rien n'arrive alors que le test est vert, vérifiez que vous regardez le bon salon et que le webhook n'a pas été désactivé dans Discord.

Types et formats

Le Type détermine comment uVersion met en forme le message avant de l'envoyer. Choisissez celui qui correspond au service pointé par l'URL, sinon le message arrivera mal formaté (ou sera rejeté par le service).

Type	Format envoyé
`discord`	Embed Discord (titre, couleur, champs).
`slack`	Payload Slack (blocs de message).
`teams`	Carte Microsoft Teams (MessageCard).
`custom`	Corps JSON entièrement défini par vous : voir Webhooks personnalisés.

Événements

Événement	Se déclenche quand…
`checkin`	Un utilisateur soumet un commit dans le dépôt.
`checkout`	Un utilisateur verrouille (check-out) un ou plusieurs fichiers.
`activity_summary`	Un résumé d'activité périodique est produit par le planificateur du serveur (quotidien / hebdomadaire).

Cochez uniquement ce dont votre canal a besoin. Sur un gros studio, checkout peut être bruyant : beaucoup d'équipes ne gardent que checkin et activity_summary.

Webhooks personnalisés

Avec le type custom, deux champs supplémentaires apparaissent : Custom Headers (JSON) et Custom Template (JSON). Ils permettent d'intégrer n'importe quel service qui accepte un POST JSON.

Template

Le template est le corps JSON envoyé. uVersion y remplace les variables entre doubles accolades par les valeurs de l'événement. Exemple :

{"text": "{{event_type}} par {{username}} dans {{repository}}"}

Variables disponibles :

Variable	Contenu
`{{event_type}}`	Type d'événement (`checkin`, `checkout`, `activity_summary`).
`{{repository}}`	Nom du dépôt.
`{{username}}`	Utilisateur à l'origine de l'événement.
`{{message}}`	Message de commit (pour un check-in).
`{{file_count}}`	Nombre de fichiers concernés.
`{{commit_hash}}`	Hash du commit.
`{{timestamp}}`	Horodatage de l'événement.

Headers

Un objet JSON d'en-têtes HTTP à joindre à la requête, par exemple un jeton d'authentification :

{"Authorization": "Bearer VOTRE_JETON"}

Par défaut {} (aucun en-tête). Les en-têtes réservés au transport (host, content-length, transfer-encoding, connection) sont retirés automatiquement et ne peuvent pas être surchargés.

JSON valide obligatoire Les champs Headers et Template sont validés à l'enregistrement. Un JSON invalide bloque la sauvegarde avec un message explicite (« Invalid JSON in headers » / « … template »). Vérifiez vos accolades et vos guillemets.

Tester, activer, supprimer

Une ligne de webhook avec le bouton « Send test » et, idéalement, le message de test reçu dans Discord.

Chaque webhook de la liste propose les actions suivantes :

Send test (icône avion) : envoie une notification de test au service et affiche un résultat en ligne (coche verte ou croix). Utile pour vérifier l'URL et le type avant de compter dessus.
Interrupteur : active / désactive le webhook sans le supprimer.
Edit : modifier n'importe quel champ.
Delete : suppression définitive (confirmation demandée).

Le test ne renvoie pas le corps de la réponse En cas d'échec, uVersion indique seulement le code HTTP renvoyé par le service (ex. « Webhook returned HTTP 404 »), jamais le contenu de la réponse. C'est volontaire (voir Sécurité). Si le test échoue, vérifiez d'abord l'URL et le type, puis les droits du webhook côté service.

Sécurité : garde SSRF

Un webhook fait émettre une requête HTTP par le serveur. Pour éviter qu'une URL malveillante ne serve à sonder le réseau interne du serveur (attaque SSRF), uVersion applique une garde stricte à la création, à la modification et au test :

Le schéma doit être http ou https. Tout autre schéma est refusé.
Le nom d'hôte est résolu en DNS, et chaque adresse IP obtenue est vérifiée. Le webhook est refusé si l'une pointe vers une adresse non publique : loopback, réseaux privés (RFC1918), link-local, broadcast, plage CGNAT 100.64.0.0/10, métadonnées cloud 169.254.169.254, ULA / link-local IPv6, et leurs équivalents IPv4-mapped-IPv6.
Les redirections HTTP ne sont pas suivies (une 307 vers un hôte interne ne peut donc pas contourner la garde).
Le corps de la réponse amont n'est jamais renvoyé au client (pas d'oracle SSRF).

En pratique : une URL de webhook doit pointer vers un service public (Discord, Slack, Teams, ou votre propre endpoint accessible depuis Internet). Une URL vers localhost, une IP privée (10.x, 192.168.x, 172.16-31.x) ou un service interne est refusée avec un message « Webhook URL refused: … ».

Pièges courants

Le type ne correspond pas au service

Envoyer un format Discord à une URL Slack (ou l'inverse) produit un message mal formaté ou un rejet côté service. Le champ Type doit correspondre à l'URL. Dans le doute, faites un Send test.

Aucun événement coché

Un webhook sans événement ne se déclenche jamais. Le client bloque la sauvegarde tant qu'aucun événement n'est sélectionné (« At least one event is required »).

URL interne refusée

Si vous testez contre un service sur votre propre machine ou votre LAN, la garde SSRF le refuse. Exposez le service sur une URL publique (ou un tunnel) pour l'utiliser comme cible de webhook.

Webhook désactivé oublié

Un webhook désactivé reste dans la liste mais n'envoie rien. Si les notifications se sont tues, vérifiez d'abord l'interrupteur d'activation avant de suspecter l'URL.