Verwalten von Webhookübermittlungen

Einführung

Wenn Sie einen Webhook erstellen, geben Sie eine URL an und abonnieren Ereignistypen. Wenn ein von Ihrem Webhook abonniertes Ereignis eintritt, sendet GitHub eine HTTP-Anforderung mit Daten über das Ereignis an die von Ihnen angegebene URL. Wenn Ihr Server für die Überwachung von Webhook-Übermittlungen unter dieser URL eingerichtet ist, kann er beim Empfang Aktionen ausführen.

In diesem Artikel wird beschrieben, wie Sie Code verfassen können, damit Ihr Server Webhook-Übermittlungen überwachen und darauf reagieren kann. Sie testen Ihren Code, indem Sie Ihren Computer oder Codespace als lokalen Server verwenden.

Setup

Zum lokalen Testen des Webhooks können Sie eine Webhook-Proxy-URL verwenden, um Webhooks von GitHub an den Computer oder Codespace weiterzuleiten. In diesem Artikel wird „smee.io“ verwendet, um eine Webhook-Proxy-URL bereitzustellen und Webhooks weiterzuleiten.

Abrufen einer Webhook-Proxy-URL

1. Navigiere im Browser zu https://smee.io/.
2. Klicke auf Neuen Kanal starten.
3. Kopiere die vollständige URL unter „Webhook-Proxy-URL“. Sie werden diese URL in den folgenden Einrichtungschritten verwenden.

Weiterleiten von Webhooks

1. Wenn smee-client noch nicht installiert ist, führen Sie den folgenden Befehl auf Ihrem Terminal aus:

   Shell

   npm install --global smee-client
   

2. Um weitergeleitete Webhooks von smee.io zu empfangen, führen Sie den folgenden Befehl am Terminal aus. Ersetze WEBHOOK_PROXY_URL durch deine Webhook-Proxy-URL von früher.

   Shell

   smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000
   

   Ungefähr folgende Ausgabe sollte angezeigt werden. WEBHOOK_PROXY_URL ist dabei deine Webhook-Proxy-URL:

   Shell

   Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
   Connected WEBHOOK_PROXY_URL
   

   Beachten Sie, dass der Pfad /webhook und der Port 3000 ist. Sie werden diese Werte später verwenden, wenn Sie Code zur Verarbeitung von Webhook-Übermittlungen schreiben.

3. Fahren Sie mit der Ausführung fort, während Sie Ihren Webhook testen. Wenn Sie die Weiterleitung von Webhooks beenden möchten, geben Sie Strg+C . ein.

Erstellen eines Webhooks

1. Erstellen Sie einen Webhook mit den folgenden Einstellungen. Weitere Informationen findest du unter Erstellen von Webhooks.

   • Verwenden Sie für die URL Ihre vorhergehende Webhook-Proxy-URL..
   • Wenn Sie über eine Option zum Auswählen des Inhaltstyps verfügen, verwenden Sie JSON.

Verfassen von Code zur Verarbeitung von Webhook-Übermittlungen

Zur Verarbeitung von Webhook-Übermittlungen müssen Sie Code verfassen, der:

• Ihren Server zum Überwachen von Anforderungen an Ihre Webhook-URL initialisiert
• Die HTTP-Header und den Text aus der Anforderung liest
• Als Reaktion auf die Anforderung die gewünschte Aktion ausführt

Sie können jede Programmiersprache verwenden, die auf Ihrem Server ausgeführt werden kann.

In den folgenden Beispielen wird beim Empfang einer Webhook-Übermittlung eine Nachricht gedruckt. Sie können den Code jedoch so ändern, dass eine andere Aktion ausgeführt wird, z. B. dass eine Anforderung an die GitHub-API gestellt oder eine Pufferzeit-Nachricht gesendet wird.

Ruby-Beispiel

In diesem Beispiel wird das Ruby-Gem Sinatra verwendet, um Routen zu definieren und HTTP-Anforderungen zu verarbeiten. Weitere Informationen findest du in der Infodatei zu Sinatra.

Ruby-Beispiel: Installieren von Abhängigkeiten

Um dieses Beispiel anwenden zu können, muss das Sinatra-Gem im Ruby-Projekt installiert werden. Dazu kannst du z. B. Bundler verwenden:

1. Wenn Bundler noch nicht installiert ist, führst du den folgenden Befehl am Terminal aus:

   Shell

   gem install bundler
   

2. Wenn du noch keine Gem-Datei für deine App hast, führst du den folgenden Befehl am Terminal aus:

   Shell

   bundle init
   

3. Wenn du noch keine Datei „Gemfile.lock“ für deine App hast, führst du den folgenden Befehl am Terminal aus:

   Shell

   bundle install
   

4. Installieren Sie das Sinatra-Gem durch Ausführen des folgenden Befehls am Terminal:

   Shell

   bundle add sinatra
   

Ruby-Beispiel: Verfassen des Codes

Erstellen Sie eine Ruby-Datei mit folgendem Inhalt. Ändern Sie den Code zum Bearbeiten der von Ihrem Webhook abonnierten Ereignistypen sowie des ping-Ereignisses, das GitHub sendet, wenn Sie einen Webhook erstellen. In diesem Beispiel werden issues- und ping-Ereignisse behandelt.

# These are the dependencies for this code. You installed the `sinatra` gem earlier. For more information, see "[Ruby example: Install dependencies](#ruby-example-install-dependencies)." The `json` library is a standard Ruby library, so you don't need to install it.
require 'sinatra'
require 'json'

# The `/webhook` route matches the path that you specified for the smee.io forwarding. For more information, see "[Forward webhooks](#forward-webhooks)."
#
# Once you deploy your code to a server and update your webhook URL, you should change this to match the path portion of the URL for your webhook.
post '/webhook' do

  # Respond to indicate that the delivery was successfully received.
  # Your server should respond with a 2XX response within 10 seconds of receiving a webhook delivery. If your server takes longer than that to respond, then GitHub terminates the connection and considers the delivery a failure.
  status 202

  # Check the `X-GitHub-Event` header to learn what event type was sent.
  # Sinatra changes `X-GitHub-Event` to `HTTP_X_GITHUB_EVENT`.
  github_event = request.env['HTTP_X_GITHUB_EVENT']

  # You should add logic to handle each event type that your webhook is subscribed to.
  # For example, this code handles the `issues` and `ping` events.
  #
  # If any events have an `action` field, you should also add logic to handle each action that you are interested in.
  # For example, this code handles the `opened` and `closed` actions for the `issue` event.
  #
  # For more information about the data that you can expect for each event type, see "[AUTOTITLE](/webhooks/webhook-events-and-payloads)."
  if github_event == "issues"
    data = JSON.parse(request.body.read)
    action = data['action']
    if action == "opened"
      puts "An issue was opened with this title: #{data['issue']['title']}"
    elsif action == "closed"
      puts "An issue was closed by #{data['issue']['user']['login']}"
    else
      puts "Unhandled action for the issue event: #{action}"
    end
  elsif github_event == "ping"
    puts "GitHub sent the ping event"
  else
    puts "Unhandled event: #{github_event}"
  end
end

require 'sinatra'
require 'json'

post '/webhook' do

  status 202

  github_event = request.env['HTTP_X_GITHUB_EVENT']

  if github_event == "issues"
    data = JSON.parse(request.body.read)
    action = data['action']
    if action == "opened"
      puts "An issue was opened with this title: #{data['issue']['title']}"
    elsif action == "closed"
      puts "An issue was closed by #{data['issue']['user']['login']}"
    else
      puts "Unhandled action for the issue event: #{action}"
    end
  elsif github_event == "ping"
    puts "GitHub sent the ping event"
  else
    puts "Unhandled event: #{github_event}"
  end
end

# These are the dependencies for this code. You installed the `sinatra` gem earlier. For more information, see "[Ruby example: Install dependencies](#ruby-example-install-dependencies)." The `json` library is a standard Ruby library, so you don't need to install it.
require 'sinatra'
require 'json'

# The `/webhook` route matches the path that you specified for the smee.io forwarding. For more information, see "[Forward webhooks](#forward-webhooks)."
#
# Once you deploy your code to a server and update your webhook URL, you should change this to match the path portion of the URL for your webhook.
post '/webhook' do

  # Respond to indicate that the delivery was successfully received.
  # Your server should respond with a 2XX response within 10 seconds of receiving a webhook delivery. If your server takes longer than that to respond, then GitHub terminates the connection and considers the delivery a failure.
  status 202

  # Check the `X-GitHub-Event` header to learn what event type was sent.
  # Sinatra changes `X-GitHub-Event` to `HTTP_X_GITHUB_EVENT`.
  github_event = request.env['HTTP_X_GITHUB_EVENT']

  # You should add logic to handle each event type that your webhook is subscribed to.
  # For example, this code handles the `issues` and `ping` events.
  #
  # If any events have an `action` field, you should also add logic to handle each action that you are interested in.
  # For example, this code handles the `opened` and `closed` actions for the `issue` event.
  #
  # For more information about the data that you can expect for each event type, see "[AUTOTITLE](/webhooks/webhook-events-and-payloads)."
  if github_event == "issues"
    data = JSON.parse(request.body.read)
    action = data['action']
    if action == "opened"
      puts "An issue was opened with this title: #{data['issue']['title']}"
    elsif action == "closed"
      puts "An issue was closed by #{data['issue']['user']['login']}"
    else
      puts "Unhandled action for the issue event: #{action}"
    end
  elsif github_event == "ping"
    puts "GitHub sent the ping event"
  else
    puts "Unhandled event: #{github_event}"
  end
end

Ruby-Beispiel: Testen des Codes

Zum Testen Ihres Webhooks können Sie Ihren Computer oder Codespace als lokalen Server einsetzen. Wenn Sie mit diesen Schritten Probleme haben, sehen Sie unter Problembehandlung nach.

1. Stellen Sie sicher, dass Sie Webhooks weiterleiten. Wenn Sie keine Webhooks mehr weiterleiten, führen Sie die Schritte aus Weiterleiten von Webhooks erneut aus.

2. Führen Sie in einem separaten Terminalfenster den folgenden Befehl aus, um einen lokalen Server auf Ihrem Computer oder Codespace zu starten. Ersetzen Sie FILE_PATH durch den Pfad zu der Datei, in der Ihr Code aus dem vorherigen Abschnitt gespeichert ist. Achten Sie darauf, dass PORT=3000 dem Port entspricht, den Sie im vorherigen Schritt für die Webhook-Weiterleitung angegeben haben.

   Shell

   PORT=3000 ruby FILE_NAME
   

   Es sollte eine Ausgabe wie etwa „Sinatra has taken the stage on 3000“ zu sehen sein.

3. Lösen Sie den Webhook aus. Wenn Sie beispielsweise einen Repository-Webhook erstellt haben, der das issues-Ereignis abonniert hat, öffnen Sie einen Sachverhalt in Ihrem Repository. Sie können auch eine vorherige Webhook-Übermittlung erneut übermitteln. Weitere Informationen findest du unter Erneutes Zustellen von Webhooks.

4. Navigiere zu deiner Webhook-Proxy-URL auf „smee.io“. Es sollte ein Ereignis angezeigt werden, das dem ausgelösten oder erneut übermittelten Ereignis entspricht. Das zeigt, dass GitHub erfolgreich eine Webhook-Übermittlung an die von Ihnen angegebene Nutzdaten-URL gesendet hat.

5. Im Terminalfenster, in dem Sie smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000 ausgeführt haben, sollte etwas wie POST http://127.0.0.1:3000/webhook - 202 zu sehen sein. Das zeigt, dass smee Ihren Webhook erfolgreich an Ihren lokalen Server weitergeleitet hat.

6. Im Terminalfenster, in dem Sie PORT=3000 ruby FILE_NAME ausgeführt haben, sollte eine Nachricht angezeigt werden, die dem gesendeten Ereignis entspricht. Wenn Sie z. B. den Beispielcode von oben verwenden und das ping-Ereignis erneut übermittelt haben, sollte „GitHub hat das Ping-Ereignis gesendet“ angezeigt werden. Möglicherweise werden auch andere Zeilen angezeigt, die Sinatra automatisch druckt.

7. Geben Sie in beiden Terminalfenstern Strg+C ein, um die Überwachung auf weitergeleitete Webhooks durch den lokalen Server zu beenden.

Problembehandlung

Wenn die in den Testschritten beschriebenen erwarteten Ergebnisse nicht angezeigt werden, versuchen Sie Folgendes:

• Stellen Sie sicher, dass Ihr Webhook Ihre Webhook-Proxy-URL (Smee.io-URL) verwendet. Weitere Informationen zur Webhook-Proxy-URL sind unter „Abrufen einer Webhook-Proxy-URL“ zu finden. Weitere Informationen zu Ihren Webhook-Einstellungen finden Sie unter „Erstellen von Webhooks“.
• Stellen Sie sicher, dass sowohl der Smee-Client als auch der lokale Server ausgeführt werden. Diese Prozesse werden in zwei separaten Terminalfenstern ablaufen.
• Sehen Sie nach Fehlern in den Terminalfenstern, in denen Sie den Smee-Client und den lokalen Server ausführen.
• Überprüfen Sie GitHub, um sicherzustellen, dass eine Webhook-Übermittlung ausgelöst wurde. Weitere Informationen findest du unter Anzeigen von Webhookübermittlungen.
• Überprüfen Sie Ihre Webhook-Proxy-URL auf „smee.io“. Es sollte ein Ereignis angezeigt werden, das dem ausgelösten oder erneut übermittelten Ereignis entspricht. Das zeigt, dass GitHub erfolgreich eine Webhook-Übermittlung an die von Ihnen angegebene Nutzdaten-URL gesendet hat.

Nächste Schritte

In diesem Artikel wurde das Verfassen von Code zur Verarbeitung von Webhook-Übermittlungen veranschaulicht. Außerdem wurde gezeigt, wie Sie Ihren Code mit Ihrem Computer oder Codespace als lokalem Server und durch Weiterleitung von Webhook-Übermittlungen von GitHub an Ihren lokalen Server über smee.io testen können. Nachdem Sie den Code getestet haben, möchten Sie den Code vielleicht ändern und den Code auf einem Server bereitstellen.

Bearbeiten des Codes

Dieser Artikel enthält grundlegende Beispiele, in denen beim Empfang einer Webhook-Übermittlung eine Nachricht gedruckt wird. Vielleicht möchten Sie den Code ändern, damit eine andere Aktion ausgeführt wird. Sie können z. B. den Code ändern, um:

• eine Anforderung an die GitHub-API zu senden
• eine Nachricht auf Slack zu senden
• Protokollereignisse
• ein externes Projektmanagementtool zu aktualisieren

zu überprüfen, ob die Webhook-Übermittlung von GitHub stammt

In Ihrem Code zur Verarbeitung von Webhook-Übermittlungen sollten Sie überprüfen, ob die Übermittlung von GitHub stammt, bevor die Übermittlung weiter verarbeitet wird. Weitere Informationen findest du unter Validating webhook deliveries.

Bereitstellen des Codes auf einem Server

In diesem Artikel wurde erläutert, wie Sie Ihren Computer oder Codespace beim Entwickeln ihres Codes als Server einsetzen können. Wenn die App für den Einsatz in der Produktion bereit ist, sollten Sie Ihren Code auf einem dedizierten Server bereitstellen.

Dabei müssen Sie ihren Code gegebenenfalls so aktualisieren, dass er den Host und den Port angibt, den Ihr Server überwacht.

Aktualisieren der Webhook-URL

Sobald Sie einen für den Empfang von Webhook-Datenverkehr von GitHub eingerichteten Server haben, müssen Sie die URL in den Webhook-Einstellungen aktualisieren. „smee.io“ sollte zur Weiterleitung der Webhooks in der Produktion nicht verwendet werden.

Bewährte Methoden befolgen

Bei den Webhooks sollten bewährte Methoden befolgt werden. Weitere Informationen findest du unter Bewährte Methoden für die Verwendung von Webhooks.

Weiterführende Themen

• Erstellen einer GitHub-App, die auf Webhookereignisse reagiert
• Bewährte Methoden für die Verwendung von Webhooks