Informationen zu Webhooks und GitHub Apps
Webhooks ermöglichen es deinem GitHub App, Echtzeitbenachrichtigungen zu erhalten, wenn Ereignisse auf GitHub auftreten, z. B. wenn jemand einen Commit pusht oder einen Pull Request in einem Repository öffnet, auf das deine App zugreifen kann. Weitere Informationen zu Webhooks findest du unter „Informationen zu Webhooks“. Ein Tutorial, das die Verwendung von Webhooks mit einer GitHub App veranschaulicht, findest du unter Erstellen einer GitHub-App, die auf Webhookereignisse reagiert.
Du kannst deine GitHub App so konfigurieren, dass sie Webhooks für bestimmte Ereignisse auf GitHub empfängt und automatisch darauf reagiert. Weitere Informationen über die Arten von Webhooks, die du empfangen kannst, findest du unter „Webhook-Ereignisse und -Nutzlasten“.
Um Webhookereignisse in deiner GitHub App zu empfangen, musst du Webhooks für deine GitHub App-Registrierung aktivieren und eine Webhook-URL angeben, an die GitHub die Webhooknutzdaten sendet.
Wenn deine GitHub App nicht auf Webhooks reagieren muss oder nur für die Authentifizierung verwendet wird, kannst du die Webhookfunktion für deine GitHub App-Registrierung deaktivieren. Du musst keine Webhook-URL angeben.
Weitere Informationen zum Registrieren einer GitHub App findest du unter Registrieren einer GitHub-App. Weitere Informationen zum Ändern der Webhooks, die von einer GitHub App-Registrierung abonniert werden, findest du unter Ändern einer GitHub-App-Registrierung.
Auswählen einer Webhook-URL
Wenn du Webhooks für deine GitHub App-Registrierung aktivierst, musst du eine Webhook-URL angeben. Die Webhook-URL ist die Adresse eines Webservers, der die Webhookereignisnutzdaten empfängt, die an deine GitHub App gesendet werden. Der Server kann dann auf der Grundlage des Inhalts der Nutzdaten Aktionen ausführen. Du solltest einen Webserver auswählen, der für das Volumen des Webhookdatenverkehrs geeignet ist, der durch deine GitHub App fließen wird.
Auswählen einer Webhook-URL für Entwicklung und Tests
Während du deine App entwickelst und testest, kannst du einen Webhook-Nutzdatenbereitstellungsdienst wie Smee verwenden, um Webhooknutzdaten zu erfassen und an deine lokale Entwicklungsumgebung weiterzuleiten. Verwende Smee niemals für eine Anwendung in der Produktion, da Smee-Kanäle nicht authentifiziert oder sicher sind. Alternativ kannst du ein Tool wie ngrok, localtunnel oder die Hookdeck-Konsole verwenden, das deinen lokalen Computer für das Internet verfügbar macht, um die Nutzdaten zu empfangen.
Erstellen einer Webhook-URL mit Smee
Du kannst Smee verwenden, um eine eindeutige Domäne zu erstellen, in der GitHub Webhooknutzdaten senden kann, ohne deine lokale Entwicklung für das Internet verfügbar zu machen. Smee bezeichnet diese eindeutige Domäne als „Webhook-Proxy-URL“. Du kannst die Webhook-Proxy-URL von Smee als Webhook-URL für deine GitHub App verwenden.
- Um Smee zum Erstellen einer eindeutigen Domäne zu verwenden, wechsle zu https://smee.io, und klicke auf Neuen Kanal starten.
- Befolge auf der Seite „Smee-Kanal“ die Anweisungen unter „Verwenden der CLI“, um den Smee-Client zu installieren und auszuführen.
- Um deine Smee-Webhook-URL mit deiner GitHub App zu verbinden, gib deine eindeutige Smee-Domäne in das Feld „Webhook-URL“ der Seite mit der GitHub App-Registrierung ein. Weitere Informationen findest du unter Registrieren einer GitHub-App und unter Ändern einer GitHub-App-Registrierung.
Auswählen einer Webhook-URL für die Produktion
Eine Anwendung in der Produktion, die ein geringes Volumen an Webhookdatenverkehr empfängt, kannst du auf jedem dynamischen Anwendungsserver hosten. Der serverseitige Code zur Verarbeitung des Webhooks kann das Ereignis empfangen, seine JSON-Nutzlast deserialisieren und entscheiden, welche Aktion ausgeführt werden soll, z. B. das Speichern der Daten in einer Datenbank oder das Aufrufen der GitHub-API.
Um ein höheres Volumen an Webhookdatenverkehr für eine große App in der Produktion zu verarbeiten, solltest du die asynchrone Webhookbehandlung auf einem dedizierten Server in Betracht ziehen. Du kannst dies durch den Einsatz einer Warteschlange erreichen, in der der Webhookhandler Daten in die Warteschlange pusht, und separate Prozesse führen nachfolgende Aktionen basierend auf den Ereignissen aus. Darüber hinaus kannst du Cloudfunktionen wie Azure Functions, AWS Lambda oder Hookdeck verwenden, um die App für die Verarbeitung großer Mengen von Webhookereignissen zu skalieren.
Schützen der Webhooks mit einem Webhookgeheimnis
Sobald du deinen Server für das Erhalten von Nutzdaten konfiguriert hast, lauscht dieser auf jegliche Nutzdaten, die zu dem von dir konfigurierten Endpunkt gesendet werden. Aus Sicherheitsgründen solltest du eingehende Anforderungen nur auf von GitHub stammende Anforderungen beschränken. Dazu kannst du ein Webhookgeheimnis für deine App erstellen.
Um ein Webhookgeheimnis für deine GitHub-App zu erstellen, gib unter „Webhookgeheimnis“ auf der Seite mit der GitHub App-Registrierung ein geheimes Token ein. Du solltest eine zufällige Textzeichenfolge mit hoher Entropie auswählen. Weitere Informationen findest du unter Registrieren einer GitHub-App und unter Ändern einer GitHub-App-Registrierung.
Nachdem du ein Webhookgeheimnis für deine App erstellt hast, musst du deinen Server so konfigurieren, dass das geheime Webhooktoken sicher gespeichert und überprüft wird. Weitere Informationen findest du unter Validierung von Webhook-Zustellung.
Abonnieren von Webhookereignissen
Du kannst deine GitHub App abonnieren, um Webhooknutzlasten für bestimmte Ereignisse zu empfangen. Die spezifischen Webhookereignisse, die du für deine GitHub App-Registrierung auswählen kannst, werden durch den Typ der Berechtigungen bestimmt, die du für deine App ausgewählt hast. Du musst zuerst die Berechtigungen auswählen, über die deine App verfügen soll, und dann kannst du deine App für Webhookereignisse abonnieren, die sich auf diesen Berechtigungssatz beziehen. Weitere Informationen findest du unter Auswählen von Berechtigungen für eine GitHub-App.
Wenn du beispielsweise möchtest, dass deine App immer dann eine Webhookereignisnutzlast erhält, wenn ein neues Problem in deinem Repository geöffnet wird, musst du deiner App zunächst die Berechtigung für den Zugriff auf „Probleme“ unter „Repositoryberechtigungen“ erteilen. Dann kannst du unter „Ereignisse abonnieren“ „Probleme“ auswählen.
Weitere Informationen zu den Berechtigungen, die für jedes Webhookereignis erforderlich sind, findest du unter „Webhook-Ereignisse und -Nutzlasten“.