Nachdem wir uns mit den Grundlagen von Webhooks vertraut gemacht haben, gehen wir nun den Prozess durch, der zum Ausbauen unserer eigenen webhookunterstützten Integration erforderlich ist. In diesem Tutorial erstellen wir einen Repositorywebhook, der die Popularität unseres Repositorys basierend auf der Anzahl der pro Tag eingehenden Issues auflistet.
Die Erstellung eines Webhooks erfolgt in zwei Schritten. Du musst zunächst festlegen, auf welche Ereignisse dein Webhook lauschen soll. Anschließend musst du deinen Server für Empfang und Verwaltung der Nutzdaten einrichten.
Du kannst die REST-API verwenden, um Repository, Organisation und App-Webhooks zu verwalten. Du kannst Webhookübermittlungen für einen Webhook auflisten oder eine individuelle Übermittlung für einen Webhook abrufen und erneut ausführen, der in eine externe App oder einen Dienst integriert werden kann. Du kannst die REST-API auch verwenden, um die Konfiguration des Webhooks zu ändern. Du kannst beispielsweise die Nutzlast-URL, den Inhaltstyp, die SSL-Überprüfung und das Geheimnis ändern. Weitere Informationen findest du unter:
Verfügbarmachen des Localhosts im Internet
Im Rahmen dieses Tutorials verwenden wir einen lokalen Server, um Webhookereignisse von GitHub zu empfangen.
Zunächst müssen wir unsere lokale Entwicklungsumgebung im Internet verfügbar machen, damit GitHub Ereignisse liefern kann. Wir verwenden dazu ngrok.
ngrok ist kostenlos für alle gängigen Betriebssysteme verfügbar. Weitere Informationen findest du auf der ngrok-Downloadseite.
Nach der Installation von ngrok kannst du deinen Localhost verfügbar machen, indem du über die Befehlszeile ./ngrok http 4567 ausführst. 4567 ist die Portnummer, auf der unser Server auf Meldungen lauscht. Du solltest eine Zeile sehen, die wie folgt aussieht:
$ Forwarding http://7e9ea9dc.ngrok.io -> 127.0.0.1:4567Notiere dir die *.ngrok.io-URL. Wir werden sie für die Einrichtung des Webhooks verwenden.
Einrichten eines Webhooks
Du kannst Webhooks in einer Organisation oder in einem bestimmten Repository installieren.
Zum Einrichten eines Webhooks gehe zur Einstellungsseite des Repositorys oder der Organisation. Klicke von dort aus auf Webhooks und dann auf Webhook hinzufügen.
Alternativ kannst du einen Webhook über die Webhook-API erstellen und verwalten.
Bevor du Webhooks verwenden kannst, sind einige Konfigurationsoptionen für sie erforderlich. Diese Einstellungen werden im Folgenden einzeln erläutert.
URL der Nutzlast
Hinweis: GitHub-Webhooks unterstützen derzeit nicht IPv6, dies wird aber in Zukunft ergänzt. Der /meta-REST-API-Endpunkt gibt IPv6-Bereiche zurück, um diesen Übergang zu ermöglichen.
Die Payload-URL ist die URL des Servers, der die Webhook-POST-Anforderungen empfängt.
Da die Entwicklung lokal für das Tutorial erfolgt, legen wir die *.ngrok.io-URL fest, gefolgt von /payload. Beispiel: http://7e9ea9dc.ngrok.io/payload.
Inhaltstyp
Webhooks können mithilfe unterschiedlicher Inhaltstypen übermittelt werden:
- Der Inhaltstyp
application/jsonbietet die JSON-Nutzdaten direkt als Text derPOST-Anforderung. - Der Inhaltstyp
application/x-www-form-urlencodedsendet die JSON-Nutzdaten als Formularparameter namenspayload.
Wähle die Einstellung aus, die deinen Anforderungen entspricht. Für dieses Tutorial ist der Standardinhaltstyp application/json in Ordnung.
Secret
Durch das Festlegen eines Webhookgeheimnisses kannst du sicherstellen, dass an die Nutzlast-URL gesendete POST-Anforderungen von GitHub Enterprise Server kommen. Wenn du einen geheimen Schlüssel festlegst, erhältst du die Header X-Hub-Signature und X-Hub-Signature-256 in der Webhook-POST-Anforderung. Weitere Informationen dazu, wie du ein Geheimnis mit einem Signaturheader verwendest, um deine Webhooknutzdaten zu schützen, findest du unter Sichern deiner Webhooks.
SSL-Überprüfung
Wenn deine „Nutzlast-URL“ eine sichere Website (HTTPS) ist, hast du die Möglichkeit, die SSL-Überprüfungseinstellungen zu konfigurieren. Wenn deine „Nutzlast-URL“ nicht sicher ist (HTTP), zeigt GitHub diese Option nicht an. Standardmäßig überprüft GitHub das SSL-Zertifikat deiner Website beim Bereitstellen von Webhook-Nutzlasten. Die SSL-Überprüfung stellt sicher, dass Hook-Nutzlasten sicher an deinen URL-Endpunkt übermittelt werden. Du hast die Möglichkeit, SSL zu deaktivieren, aber wir empfehlen, SSL-Überprüfung aktivieren beizubehalten.
Aktiv
Webhookzustellungen sind standardmäßig „Aktiv“. Du kannst die Zustellung von Webhooknutzdaten während der Entwicklung deaktivieren, indem du die Auswahl von „Aktiv“ aufhebst.
Ereignisse
Ereignisse sind das Kernstück von Webhooks. Diese Webhooks werden ausgelöst, wenn eine bestimmte Aktion im Repository ausgeführt wird. Die Nutzdaten-URL des Servers fängt diese ab und reagiert darauf.
Eine vollständige Liste der Webhookereignisse und Informationen dazu, wann diese ausgeführt werden, findest du in der Referenz zur Webhooks-API.
Da der Webhook Issues in einem Repository behandelt, klicken wir auf Einzelne Ereignisse auswählen und dann auf Issues. Stelle sicher, dass zum Empfangen von Problemereignissen für ausgelöste Webhooks Aktiv ausgewählt ist. Du kannst auch alle Ereignisse mithilfe der Standardoption auswählen.
Wenn du fertig bist, klicke auf Webhook hinzufügen.
Nachdem du den Webhook erstellt hast, ist es an der Zeit, den lokalen Server einzurichten, um den Webhook zu testen. Navigiere zu Konfigurieren des Servers, um zu erfahren, wie du dabei vorgehen musst.
Platzhalterereignis
Zum Konfigurieren eines Webhooks für alle Ereignisse verwende das Platzhalterzeichen (*), um die Webhookereignisse anzugeben. Wenn du das Platzhalterereignis hinzufügst, ersetzen wir alle vorhandenen Ereignisse, die du mit dem Platzhalterereignis konfiguriert hast, und senden dir Nutzdaten für alle unterstützten Ereignisse zu. Außerdem erhältst du automatisch alle neuen Ereignisse, die wir in Zukunft hinzufügen.