Webhooks

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 (einem auf dem Server versionierten Projekt) eintritt: ein Check-in 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.

Webhook erstellen

1. Den Webhooks-Tab öffnen

Wählen Sie im Admin-Panel zuerst das Repository im Selektor der Zeile PROJECT, öffnen Sie dann den Webhooks-Tab derselben Zeile: Ein Webhook gehört zu einem Repository. Ein Repository, das keinen hat, zeigt No webhooks configured.

2. Das Formular öffnen

Klicken Sie oben rechts im Tab auf Add Webhook. Das Fenster Create Webhook öffnet sich, leer.

3. Die Felder ausfüllen

Zwei Felder sind erforderlich, Name und URL, und mindestens ein Ereignis muss in Events ausgewählt sein (das sind anklickbare Pills, keine Dropdown-Liste). Der Type muss zu dem Dienst passen, auf den die URL zeigt.

So erhalten Sie die URL auf der Discord-Seite: Kanaleinstellungen → Integrationen → Webhooks → Neuer Webhook → URL kopieren, im Tutorial unten ausführlich. 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.

4. Bestätigen, dann einen Test senden

Klicken Sie auf Create Webhook. Der Webhook erscheint in der Liste, aktiv. Klicken Sie in seiner Zeile auf das Flugzeug-Symbol Send test: uVersion sendet eine Testbenachrichtigung an den Dienst und zeigt das Ergebnis am Ende der Zeile an, ein grünes Häkchen oder ein Kreuz mit dem zurückgegebenen HTTP-Code. Tun Sie es jetzt: Es ist die einzige Möglichkeit zu wissen, dass URL und Typ stimmen, bevor Sie sich auf diesen Webhook verlassen.

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

1. Öffnen Sie Discord und gehen Sie auf Ihren Server. Wählen (oder erstellen) Sie den Textkanal, der die Benachrichtigungen erhalten soll, zum Beispiel #uversion.
2. Fahren Sie mit der Maus über den Kanalnamen und klicken Sie auf das Zahnrad-Symbol („Kanal bearbeiten“).
3. Öffnen Sie im linken Menü den Tab Integrationen.
4. Klicken Sie auf Webhooks und dann auf Neuer Webhook. Discord erstellt automatisch einen, der an diesen Kanal gebunden ist.
5. 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.
6. Klicken Sie auf Webhook-URL kopieren. Die URL sieht so aus wie https://discord.com/api/webhooks/123456789/AbCdEf....

Auf der uVersion-Seite: die URL anbinden

Führen Sie die Prozedur Webhook erstellen oben mit diesen Werten aus: Name eine Bezeichnung für Sie (z. B. Discord équipe), URL die, die Sie gerade kopiert haben, Type discord (unverzichtbar, damit die Nachricht als Discord-Embed hinausgeht), Events checkin. Schließen Sie mit Send test ab: Eine Nachricht 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).

Ereignisse

Zwei Ereignisse werden tatsächlich vom Server ausgegeben:

Haken Sie nur an, was Ihr Kanal braucht. In der Praxis ist die nützliche Kombination checkin für den Arbeits-Feed des Teams und activity_summary für einen periodischen Überblick.

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:

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.

Testen, aktivieren, löschen

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).

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.