Allgemein, Technik
Veröffentlicht am 27. Mai 2022
Webhooks sind benutzerdefinierte HTTP POST-Aufrufe an eine bestimmte Internetadresse. Es handelt sich hier um einen leichtgewichtigen Mechanismus, der es ermöglicht, in Remoteanwendungen Push-Nachrichten aus Jira zu erhalten.
Als Auslöser für den Webhook werden ein oder mehrere Ereignisse definiert, zum Beispiel das Erstellen und/oder Ändern von Vorgängen in Jira. Treten diese Ereignisse ein, wird der Webhook ausgeführt. Daraufhin kann eine Remoteanwendung in gewünschter Weise reagieren und die durch den Webhook versendeten Daten verarbeiten. Die Daten, die versendet werden, sind an das jeweilige Ereignis angepasst. Ein Webhook, der beim Anlegen eines Vorganges ausgelöst wird, sendet vorgangsbezogene Informationen als JSON an die konfigurierte URL – zum Beispiel das zugehörige Projekt, den:die Benutzer:in, der:die den Vorgang erstellt hat, den Vorgangstyp und mehr.
Es gibt zwei Möglichkeiten, Webhooks in Jira anzulegen: Entweder über die REST-Schnittstelle per API-Aufruf an [JIRA_CLOUD_URL]/rest/webhooks/1.9/webhook oder über die Jira-Administrationsseite. Webhooks können demnach auch aus Remoteanwendungen heraus erstellt und konfiguriert werden.
Wir betrachten hier den Weg über die Jira-Oberfläche. Um einen Webhook in Jira anzulegen, sind Administratorberechtigungen erforderlich. Vorhandene Webhooks werden unter Settings – System – ADVANCED – WebHooks aufgeführt.
Um einen neuen Webhook zu erstellen, wählt man Create a Webhook.
Name, Status und URL sind erforderliche Angaben. Eine Beschreibung kann nähere Informationen zu dem Webhook enthalten. Mit Hilfe des Status „Enabled/Disabled“ wird der Webhook entsprechend aktiviert oder deaktiviert.
Es können eine Reihe von Variablen an die URL gehängt werden, um beispielsweise den Vorgangsschlüssel oder die Projekt-ID direkt in der URL zu übertragen.
In diesem Abschnitt wird festgelegt, welche Ereignisse den HTTP-Request auslösen sollen:
Ich erstelle hier beispielhaft einen Webhook, der beim Erstellen, Ändern und Löschen von Vorgängen (einschließlich Kommentare) eines bestimmten Projektes ausgelöst wird.
Bei Ereignissen, die sich auf Vorgänge beziehen, kann die Auswahl der Vorgänge per JQL eingeschränkt werden. Hierfür füge ich das JQL ein, das auf meine Auswahl zutrifft:
Soll beim Auslösen des Webhooks nur die konfigurierte URL aufgerufen werden, wird ein Häkchen bei Exclude body gesetzt. Ich möchte aber auch die Payload (JSON) versenden, um Informationen über den Vorgang wie „summary“, „reporter“ oder Änderungen auswerten zu können. Deshalb bleibt diese Checkbox leer.
Bei vorgangsbezogenen Ereignissen (zum Beispiel Vorgang anlegen, ändern) werden die Daten analog zur Jira-REST-API (ohne expand) geliefert:
Der Block „changelog“ enthält eine Liste mit Einträgen für jedes geänderte Feld:
Wird ein Kommentar hinzugefügt, geändert oder gelöscht, enthält das JSON das Feld „comment“:
Standardmäßig ist der Webhook so eingestellt, dass ereignisrelevante Daten per JSON (Exclude body ist nicht selektiert) übertragen werden. Bei vorgangsbezogenen Ereignissen (zum Beispiel Vorgang anlegen, ändern) werden die Daten analog zur Jira-REST-API-Anfrage (ohne expand) geliefert:
{
„timestamp“
„event“
„user“: {
…
},
„issue“: {
…
},
„changelog“ : {
…
},
„comment“ : {
…
}
}
Der Block „changelog“ wird nur beim „issue updated Ereignis“ übertragen und enthält eine Liste mit Einträgen für jedes geänderte Feld:
„changelog“: {
„items“: [
{
„toString“: „A new summary.“,
„to“: null,
„fromString“: „What is going on here?????“,
„from“: null,
„fieldtype“: „jira“,
„field“: „summary“
},
{
„toString“: „New Feature“,
„to“: „2“,
„fromString“: „Improvement“,
„from“: „4“,
„fieldtype“: „jira“,
„field“: „issuetype“
},
],
„id“: 10124
}
Hier kommst du zur Atlassian-Dokumentation für Webhooks für Jira Server: https://developer.atlassian.com/server/jira/platform/webhooks/
Hast du noch Fragen? Dann schreib diese gerne in die Kommentare oder schick eine Mail an: atlassian@team-neusta.de
