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 das Verwenden von Webhooks mit einer GitHub App veranschaulicht, findest du unter Erstellen einer GitHub-App, die auf Webhook-Ereignisse 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 Webhook-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 Webhook-Ereignisdaten 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 Webhook-Payloads senden kann, ohne deine lokale Entwicklung im Internet freizugeben. 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 Ä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 können Sie Cloudfunktionen wie Azure Functions, AWS Lambda oder Hookdeck verwenden, um die App für die Verarbeitung großer Mengen von Webhook-Ereignissen zu skalieren.
So sichern Sie Ihre Webhooks mit einem Webhook-Geheimnis
Sobald du deinen Server für den Empfang von Payloads konfiguriert hast, lauscht dieser auf alle an den Server gesendeten Payloads. 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 einen Webhook-Geheimschlüssel für Ihre GitHub App zu erstellen, geben Sie unter "Webhook-Geheimnis" ein geheimes Token auf Ihrer GitHub App Registrierungsseite ein. Du solltest eine zufällige Textzeichenfolge mit hoher Entropie auswählen. Weitere Informationen findest du unter Registrieren einer GitHub-App und Ä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 finden Sie unter Validierung der Webhook-Lieferungen.
Abonnieren von Webhook-Ereignissen
Sie können Ihre GitHub App abonnieren, um Webhook-Nutzlasten bestimmter 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 finden Sie unter Auswählen von Berechtigungen für eine GitHub App.
Wenn du beispielsweise möchtest, dass deine App den Webhook-Payload immer dann erhält, wenn ein neues Issue in deinem Repository geöffnet wird, musst du deiner App zunächst die Berechtigung für den Zugriff auf „Issues“ 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 Webhook-Nutzlasten.