Wiki

Webhooks

Ausgehende Benachrichtigungen pro Repository (Discord, Slack, Teams, custom) bei Check-in, Check-out und Aktivitätszusammenfassungen. Erstellung, Nachrichtenformat, Template-Variablen, SSRF-Schutz.

Einführung

Ein Webhook sendet eine ausgehende Benachrichtigung an einen externen Dienst (Discord, Slack, Microsoft Teams, oder eine URL Ihrer Wahl), jedes Mal wenn ein Ereignis in einem Repository eintritt: ein Check-in, ein Check-out oder eine periodische Aktivitätszusammenfassung. Es ist der einfachste Weg, ein Team auf dem Laufenden zu halten, ohne dass es den Client öffnet: Eine Nachricht landet in Ihrem Kanal, wenn jemand Arbeit einreicht.

Webhooks werden pro Repository konfiguriert, im Admin-Panel des Desktop-Clients, unter dem Tab Webhooks. Ein Repository kann mehrere Webhooks haben (zum Beispiel einen an Discord für das ganze Team, einen an ein privates Slack für die Leads).

Zugriff und Rollen

Die Verwaltung von Webhooks ist Repository-Administratoren vorbehalten: einem Super-Admin (Rolle admin) auf jedem beliebigen Repository, oder einem project_admin auf den Repositories, die er verwaltet. Andere Rollen sehen diesen Tab nicht.

Gut zu wissen Der Tab Webhooks nutzt das Multi-Webhook-System (mehrere Einträge pro Repository). Eine ältere Discord-Benachrichtigung mit einzelner URL existiert serverseitig aus Kompatibilitätsgründen noch, ist aber in diesem neuen Tab nicht sichtbar: Verwenden Sie die hier beschriebenen Webhooks.

Webhook erstellen

Das Formular Add Webhook: Name, URL, Type (discord/slack/teams/custom), Events-Kontrollkästchen, Enabled-Schalter.

Öffnen Sie das Admin-Panel, wählen Sie das Repository und dann den Tab Webhooks.
Klicken Sie auf Add Webhook.
Füllen Sie die Felder aus, dann Create.

Feld	Wert
Name	Eine Bezeichnung, um ihn wiederzufinden (z. B. `Discord équipe`). Erforderlich.
URL	Die vom Zieldienst bereitgestellte Webhook-URL. Erforderlich. Zu abgelehnten URLs siehe Sicherheit.
Type	`discord`, `slack`, `teams` oder `custom`.
Events	Eines oder mehrere von `checkin`, `checkout`, `activity_summary`. Mindestens eines ist erforderlich.
Enabled	Aktivierungsschalter (sichtbar beim Bearbeiten und aus der Liste).

So erhalten Sie die URL auf der Discord-Seite: Kanaleinstellungen → Integrationen → Webhooks → Neuer Webhook → Webhook-URL kopieren. Auf der Slack-Seite: Erstellen Sie einen Incoming Webhook in den Einstellungen der Slack-App. Auf der Teams-Seite: Connectors → Incoming Webhook auf dem Kanal.

Tutorial: Discord-Webhook

Das ist der häufigste Fall. Der Teil „URL beschaffen“ passiert vollständig in Discord, nur ein einziges Mal.

Auf der Discord-Seite: URL beschaffen

Öffnen Sie Discord und gehen Sie auf Ihren Server. Wählen (oder erstellen) Sie den Textkanal, der die Benachrichtigungen erhalten soll, zum Beispiel #uversion.
Fahren Sie mit der Maus über den Kanalnamen und klicken Sie auf das Zahnrad-Symbol („Kanal bearbeiten“).
Öffnen Sie im linken Menü den Tab Integrationen.
Klicken Sie auf Webhooks und dann auf Neuer Webhook. Discord erstellt automatisch einen, der an diesen Kanal gebunden ist.
Klicken Sie auf den erstellten Webhook, um ihn zu öffnen. Geben Sie ihm einen Namen (zum Beispiel uVersion) und prüfen Sie, dass der Ziel-Kanal der richtige ist. Ein Avatar-Bild ist optional.
Klicken Sie auf Webhook-URL kopieren. Die URL sieht so aus wie https://discord.com/api/webhooks/123456789/AbCdEf....

Halten Sie diese URL geheim Jeder, der die URL besitzt, kann Nachrichten in Ihrem Kanal posten. Committen Sie sie nicht ins Repository und teilen Sie sie nicht öffentlich. Falls sie durchsickert, löschen Sie den Webhook auf der Discord-Seite und erstellen Sie einen neuen.

Auf der uVersion-Seite: die URL anbinden

Öffnen Sie im Desktop-Client das Admin-Panel, wählen Sie das Repository und dann den Tab Webhooks.
Klicken Sie auf Add Webhook.
Name: eine Bezeichnung für Sie (z. B. Discord équipe).
URL: Fügen Sie die aus Discord kopierte URL ein.
Type: Wählen Sie discord (unverzichtbar, damit die Nachricht als Discord-Embed formatiert wird).
Events: Haken Sie die gewünschten Ereignisse an, zum Beispiel checkin.
Klicken Sie auf Create.
Klicken Sie in der Webhook-Zeile auf Send test: Eine Testnachricht sollte innerhalb weniger Sekunden im Discord-Kanal erscheinen.

Wenn der Test mit einem HTTP-Status 401 oder 404 fehlschlägt, ist die URL falsch oder der Webhook wurde auf der Discord-Seite gelöscht: Kopieren Sie die URL erneut. Wenn nichts ankommt, obwohl der Test grün ist, prüfen Sie, ob Sie den richtigen Kanal betrachten und ob der Webhook in Discord nicht deaktiviert wurde.

Typen und Formate

Der Type bestimmt, wie uVersion die Nachricht vor dem Senden formatiert. Wählen Sie denjenigen, der zu dem von der URL adressierten Dienst passt, sonst kommt die Nachricht falsch formatiert an (oder wird vom Dienst abgelehnt).

Type	Gesendetes Format
`discord`	Discord-Embed (Titel, Farbe, Felder).
`slack`	Slack-Payload (Nachrichtenblöcke).
`teams`	Microsoft-Teams-Karte (MessageCard).
`custom`	Vollständig von Ihnen definierter JSON-Body: siehe Benutzerdefinierte Webhooks.

Ereignisse

Ereignis	Wird ausgelöst, wenn…
`checkin`	Ein Benutzer einen Commit ins Repository einreicht.
`checkout`	Ein Benutzer eine oder mehrere Dateien sperrt (Check-out).
`activity_summary`	Eine periodische Aktivitätszusammenfassung vom Server-Scheduler erzeugt wird (täglich / wöchentlich).

Haken Sie nur an, was Ihr Kanal braucht. In einem großen Studio kann checkout laut werden: viele Teams behalten nur checkin und activity_summary.

Benutzerdefinierte Webhooks

Beim Typ custom erscheinen zwei zusätzliche Felder: Custom Headers (JSON) und Custom Template (JSON). Damit lässt sich jeder Dienst anbinden, der ein JSON-POST akzeptiert.

Template

Das Template ist der gesendete JSON-Body. uVersion ersetzt darin die Variablen in doppelten geschweiften Klammern durch die Werte des Ereignisses. Beispiel:

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

Verfügbare Variablen:

Variable	Inhalt
`{{event_type}}`	Ereignistyp (`checkin`, `checkout`, `activity_summary`).
`{{repository}}`	Repository-Name.
`{{username}}`	Benutzer, der das Ereignis ausgelöst hat.
`{{message}}`	Commit-Nachricht (bei einem Check-in).
`{{file_count}}`	Anzahl der betroffenen Dateien.
`{{commit_hash}}`	Commit-Hash.
`{{timestamp}}`	Zeitstempel des Ereignisses.

Headers

Ein JSON-Objekt aus HTTP-Headern, das der Anfrage beigefügt wird, zum Beispiel ein Authentifizierungstoken:

{"Authorization": "Bearer VOTRE_JETON"}

Standardmäßig {} (keine Header). Für den Transport reservierte Header (host, content-length, transfer-encoding, connection) werden automatisch entfernt und können nicht überschrieben werden.

Gültiges JSON erforderlich Die Felder Headers und Template werden beim Speichern validiert. Ungültiges JSON blockiert das Speichern mit einer expliziten Meldung („Invalid JSON in headers“ / „… template“). Prüfen Sie Ihre Klammern und Ihre Anführungszeichen.

Testen, aktivieren, löschen

Eine Webhook-Zeile mit der Schaltfläche « Send test » und, idealerweise, der in Discord empfangenen Testnachricht.

Jeder Webhook in der Liste bietet die folgenden Aktionen:

Send test (Flugzeug-Symbol): sendet eine Testbenachrichtigung an den Dienst und zeigt ein Ergebnis inline an (grünes Häkchen oder Kreuz). Nützlich, um URL und Typ zu prüfen, bevor man sich darauf verlässt.
Schalter: aktiviert / deaktiviert den Webhook, ohne ihn zu löschen.
Edit: beliebiges Feld ändern.
Delete: endgültiges Löschen (Bestätigung erforderlich).

Der Test gibt den Response-Body nicht zurück Bei einem Fehlschlag gibt uVersion nur den vom Dienst zurückgegebenen HTTP-Status an (z. B. „Webhook returned HTTP 404“), niemals den Inhalt der Antwort. Das ist beabsichtigt (siehe Sicherheit). Wenn der Test fehlschlägt, prüfen Sie zuerst URL und Typ, dann die Rechte des Webhooks auf der Dienstseite.

Sicherheit: SSRF-Schutz

Ein Webhook lässt eine HTTP-Anfrage vom Server ausgehen. Um zu verhindern, dass eine bösartige URL dazu dient, das interne Netzwerk des Servers auszukundschaften (SSRF-Angriff), wendet uVersion einen strengen Schutz bei der Erstellung, bei der Änderung und beim Test an:

Das Schema muss http oder https sein. Jedes andere Schema wird abgelehnt.
Der Hostname wird per DNS aufgelöst, und jede erhaltene IP-Adresse wird geprüft. Der Webhook wird abgelehnt, wenn eine davon auf eine nicht-öffentliche Adresse zeigt: Loopback, private Netze (RFC1918), Link-Local, Broadcast, CGNAT-Bereich 100.64.0.0/10, Cloud-Metadaten 169.254.169.254, ULA / IPv6-Link-Local und ihre IPv4-mapped-IPv6-Entsprechungen.
HTTP-Weiterleitungen werden nicht verfolgt (eine 307 zu einem internen Host kann den Schutz also nicht umgehen).
Der Response-Body der Gegenstelle wird niemals an den Client zurückgegeben (kein SSRF-Orakel).

In der Praxis: Eine Webhook-URL muss auf einen öffentlichen Dienst zeigen (Discord, Slack, Teams, oder Ihren eigenen, aus dem Internet erreichbaren Endpunkt). Eine URL zu localhost, einer privaten IP (10.x, 192.168.x, 172.16-31.x) oder einem internen Dienst wird abgelehnt, mit der Meldung „Webhook URL refused: …“.

Häufige Fallstricke

Der Typ passt nicht zum Dienst

Ein Discord-Format an eine Slack-URL zu senden (oder umgekehrt) erzeugt eine falsch formatierte Nachricht oder eine Ablehnung auf der Dienstseite. Das Feld Type muss zur URL passen. Im Zweifel führen Sie ein Send test aus.

Kein Ereignis angehakt

Ein Webhook ohne Ereignis wird nie ausgelöst. Der Client blockiert das Speichern, solange kein Ereignis ausgewählt ist („At least one event is required“).

Interne URL abgelehnt

Wenn Sie gegen einen Dienst auf Ihrer eigenen Maschine oder in Ihrem LAN testen, lehnt der SSRF-Schutz ihn ab. Machen Sie den Dienst über eine öffentliche URL (oder einen Tunnel) erreichbar, um ihn als Webhook-Ziel zu nutzen.

Vergessener deaktivierter Webhook

Ein deaktivierter Webhook bleibt in der Liste, sendet aber nichts. Wenn die Benachrichtigungen verstummt sind, prüfen Sie zuerst den Aktivierungsschalter, bevor Sie die URL verdächtigen.