Problembehandlung bei Webhooks

Fehlende Webhookübermittlungen

Wenn Sie die erwarteten Webhookübermittlungen nicht erhalten, sollten Sie den Punkt ermitteln, an dem die Zustellung fehlt.

1. Lösen Sie ein Ereignis aus, das zu einer Webhookübermittlung führen soll. Wenn Ihr Webhook beispielsweise ein Repository-Webhook ist, der das issues-Ereignis abonniert hat, können Sie einen Sachverhalt in Ihrem Repository öffnen.

2. Sehen Sie sich das Protokoll der letzten Übermittlungen für Ihren Webhook an. Informationen dazu, wie dies für jeden Webhook-Typ durchgeführt wird, finden Sie unter „Anzeigen von Webhookübermittlungen“.

   Wenn das Protokoll der letzten Lieferungen keine Übermittlung enthält, die dem Webhook-Ereignis entspricht, das Sie im vorherigen Schritt ausgelöst haben, hat GitHub keine Zustellung versucht. So identifizieren Sie die Ursache

   1. Warten Sie ein paar Minuten, und überprüfen Sie es erneut. Es kann einige Minuten dauern, bis Webhookübermittlungen angezeigt werden.

   2. Stellen Sie sicher, dass Sie ein Ereignis an dem Ort ausgelöst haben, an dem Ihr Webhook konfiguriert ist. Wenn Ihr Webhook beispielsweise ein Repository-Webhook ist, stellen Sie sicher, dass Sie das Ereignis im selben Repository ausgelöst haben, in dem Ihr Webhook konfiguriert ist.

   3. Stellen Sie sicher, dass Ihr Webhook das ausgelöste Ereignis abonniert hat. Wenn Sie beispielsweise eine Webhookübermittlung erwarten, wenn Sie ein Problem öffnen, stellen Sie sicher, dass Ihr Webhook das issues-Ereignis abonniert hat.

   4. Stellen Sie sicher, dass Ihr Webhook aktiv ist. Weitere Informationen findest du unter Deaktivieren von Webhooks.

   5. Stellen Sie sicher, dass Ihr Webhook nicht von OAuth app-Zugriffseinschränkungen betroffen ist. Wenn Ihr Webhook von einem OAuth app im Namen eines Benutzers erstellt wurde, der die OAuth app autorisiert hat, wird der Webhook automatisch deaktiviert, wenn es sich um eine Organisation oder ein Repository-Webhook für eine Organisation handelt, die den Zugriff durch die OAuth app eingeschränkt hat. Weitere Informationen finden Sie unter Informationen zu OAuth App-Zugriffseinschränkungen.

   6. Überprüfen Sie, ob Ihr Ereignis möglicherweise ein dokumentiertes Limit erreicht hat. Wenn Sie beispielsweise mehr als drei Tags gleichzeitig pushen, wird das push-Ereignis für diesen Push nicht ausgelöst. Weitere Informationen zu den dokumentierten Limits für die einzelnen Webhookereignisse finden Sie unter Webhook-Ereignisse und -Nutzlasten.

   7. Überprüfen Sie den Status von Webhooks unter githubstatus.com.

   Wenn das Protokoll der letzten Übermittlungen angibt, dass bei der Übermittlung ein Fehler aufgetreten ist, hat GitHub die Zustellung versucht, sie war aber nicht erfolgreich. Dies liegt in der Regel an einem Problem mit Ihrem Server. Sie können sich auf die folgenden Abschnitte beziehen, um den spezifischen Fehler zu beheben.

3. Sehen Sie sich die Protokolle für Ihren Server an. Die Informationen in den Protokollen hängen vom Code ab, der vom Server ausgeführt wird, um Webhookübermittlungen zu verarbeiten. Damit Sie Probleme auf Ihrem Server diagnostizieren können, können Sie ihrem Code zusätzliche Protokollanweisungen hinzufügen.

Es sind nicht mehr als 20 Webhooks zulässig

Sie können bis zu 20 Repository-, Organisations- oder globale Webhooks für jeden Ereignistyp erstellen. Wenn Sie versuchen, mehr zu erstellen, wird eine Fehlermeldung angezeigt, die besagt, dass Sie nicht mehr als 20 Webhooks haben dürfen.

Wenn Sie mehr als 20 Webhooks benötigen, können Sie einen Proxy ausführen, der Webhooks von GitHub empfängt und an eine unbegrenzte Anzahl von Ziel-URLs weiterleitet.

Der URL-Host localhost wird nicht unterstützt.

Sie können localhost oder 127.0.0.1 nicht als Weebhook-URL verwenden.

Wenn Sie Webhooks zu Testzwecken an Ihren lokalen Server übermitteln möchten, können Sie einen Webhook-Weiterleitungsdienst verwenden. Weitere Informationen sind unter „Testen von Webhooks“ oder https://smee.io/ zu finden.

Fehler beim Herstellen einer Verbindung zum Host

Der Fehler failed to connect to host tritt auf, wenn GitHub eine Webhookübermittlung versucht, aber die URL des Webhooks nicht in eine IP-Adresse auflösen konnte.

Um zu überprüfen, ob ein Hostname in eine IP-Adresse aufgelöst wird, können Sie nslookup verwenden. Wenn ihre Nutzlast-URL beispielsweise https://octodex.github.com/webhooks lautet, können Sie nslookup octodex.github.com ausführen. Wenn der Hostname nicht in eine IP-Adresse aufgelöst werden konnte, gibt der Befehl „nslookup“ an, dass der Server den Hostnamen nicht finden kann.

Verbindung zu Netzwerk fehlgeschlagen

Der Fehler failed to connect to network gibt an, dass der Server die Verbindung verweigert hat, als GitHub versucht hat, einen Webhook zu übermitteln.

Sie sollten sicherstellen, dass Ihr Server Verbindungen von IP-Adressen von GitHub zulässt. Du kannst den GET /meta-Endpunkt verwenden, um die aktuelle Liste der IP-Adressen von GitHub zu finden. Weitere Informationen findest du unter REST-API-Endpunkte für Metadaten. GitHub ändert gelegentlich seine IP-Adressen, sodass du deine IP-Zulassungsliste regelmäßig aktualisieren solltest.

Timeout

Der Fehler timed out gibt an, dass GitHub keine Antwort von Ihrem Server innerhalb von 10 Sekunden nach der Übermittlung eines Webhooks erhalten hat.

Ihr Server sollte mit einer 2xx-Antwort innerhalb von 10 Sekunden nach Erhalt einer Webhook-Übermittlung antworten. Wenn die Serverantwort länger dauert, beendet GitHub die Verbindung und kategorisiert die Zustellung als Fehler.

Um zeitnah zu antworten, solltest du eine Warteschlange einrichten, um Webhook-Nutzlasten asynchron zu verarbeiten. Dein Server kann antworten, wenn er den Webhook empfängt, und dann die Nutzlast im Hintergrund verarbeiten, ohne zukünftige Webhook-Zustellungen zu blockieren. Beispielsweise kannst du Dienste wie Hookdeck oder Bibliotheken wie Resque (Ruby), RQ (Python) oder RabbitMQ (Java) verwenden.

Das Peerzertifikat kann mit den vorhandenen Zertifizierungsstellenzertifikaten nicht authentifiziert werden.

Dieser Fehler weist darauf hin, dass es ein Problem im Zusammenhang mit den Zertifikaten Ihres Servers gibt. Die häufigsten Probleme sind:

• Ihr Server verwendet ein selbstsigniertes Zertifikat.
• Der Server sendet nicht die vollständige Zertifikatkette, wenn die Verbindung hergestellt wird.

Um das Problem zu diagnostizieren, können Sie den SSL-Servertest von SSL Labs verwenden. Dieser Dienst kann nur mit dem Standardport für HTTPS (Port 443) und nur mit Servern arbeiten, auf die über das Internet zugegriffen werden kann.

Sie können auch openssl verwenden, um das Problem zu diagnostizieren. Führen Sie hierzu openssl s_client -connect HOST:PORT in einem Terminal aus. Ersetzen Sie HOST durch den Hostnamen ihres Servers und PORT durch den Port. Beispiel: openssl s_client -connect example.com:443. Um Probleme zu identifizieren, suchen Sie in der Ausgabe nach verify error.

Ungültige HTTP-Antwort

Der Fehler invalid HTTP response tritt auf, wenn Ihr Server als Reaktion auf eine Webhookübermittlung von GitHub einen 4xx- oder 5xx-Status zurückgibt.

Sie sollten Ihren Server so konfigurieren, dass ein 2xx-Status zurückgegeben wird. Wenn Ihr Server den Status „4xx“ oder „5xx“ zurückgibt, zeichnet GitHub die Übermittlung als Fehler auf.

Webhooksübermittlungen sind in der falschen Reihenfolge

GitHub kann Webhooks in einer anderen Reihenfolge übermitteln als die Ereignisse stattgefunden haben. Wenn Sie wissen müssen, wann das Ereignis relativ zu einem anderen Ereignis aufgetreten ist, sollten Sie die Zeitstempel verwenden, die in der Übermittlungsnutzlast enthalten sind.

Webhookübermittlungen finden nicht sofort statt

Es kann einige Minuten dauern, bis Webhookübermittlungen zugestellt und im Protokoll der letzten Übermittlungen angezeigt werden. Bevor Sie annehmen, dass die Webhookübermittlung fehlgeschlagen ist, warten Sie einige Minuten, und überprüfen Sie dann erneut.

Wenn Ihr Konto einen Anstieg der Webhook-Bereitstellungen verzeichnet, kann GitHub vorübergehend die Häufigkeit der Übermittlungen an Ihr Konto drosseln. Wenn Ihre Webhook-Bereitstellungen von GitHub verlangsamt werden, zeigt die throttled_at-Eigenschaft für die betroffenen Übermittlungen jeweils den Zeitstempel an, zu dem die Übermittlung gedrosselt wurde. Sie können dies mithilfe der REST-API überprüfen, siehe „Auflisten von Bereitstellungen für einen Repository-Webhook“.

Um Verzögerungen zu vermeiden, abonnieren Sie nur die Webhook-Ereignisse, die für Ihr Konto erforderlich sind. So verringern Sie die Häufigkeit der Bereitstellungen. Siehe „Bewährte Methoden für die Verwendung von Webhooks“.

Fehler bei der Signatur-Überprüfung.

Sie sollten ein Webhook-Geheimnis und den X-Hub-Signature-256-Header verwenden, um zu überprüfen, ob eine Webhook-Zustellung von GitHub stammt. Weitere Informationen findest du unter Validierung von Webhook-Zustellung.

Wenn Sie sicher sind, dass die Nutzdaten aus GitHub stammen, die Signatur-Überprüfung jedoch fehlschlägt:

• Stellen Sie sicher, dass Sie ein Geheimnis für Ihren Webhook konfiguriert haben. Der X-Hub-Signature-256-Header ist nicht vorhanden, wenn Sie kein Geheimnis für Ihren Webhook konfiguriert haben. Weitere Informationen zu Webhook-Geheimnissen finden Sie unter „Bearbeiten von Webhooks“.
• Stellen Sie sicher, dass Sie die richtige Kopfzeile verwenden. GitHub empfiehlt, den X-Hub-Signature-256-Header zu verwenden, der den HMAC-SHA256-Algorithmus verwendet. Der X-Hub-Signature-Header verwendet den HMAC-SHA1-Algorithmus und ist nur für Legacy-Zwecke enthalten.
• Stellen Sie sicher, dass Sie den richtigen Algorithmus verwenden. Wenn Sie den X-Hub-Signature-256-Header verwenden, sollten Sie den HMAC-SHA256-Algorithmus verwenden.
• Stellen Sie sicher, dass Sie das richtige Webhook-Geheimnis verwenden. Wenn Sie den Wert Ihres Webhook-Geheimnisses nicht kennen, können Sie das Webhook-Geheimnis aktualisieren. Weitere Informationen findest du unter Bearbeiten von Webhooks.
• Stellen Sie sicher, dass die Nutzdaten und die Header vor der Überprüfung nicht geändert werden. Wenn Sie z. B. einen Proxy oder einen Lastenausgleich verwenden, stellen Sie sicher, dass der Proxy oder lastenausgleich keine Nutzdaten oder Header ändert.
• Wenn deine Sprach- und Serverimplementierung eine Zeichencodierung angibt, musst du sicherstellen, dass diese Nutzdaten als UTF-8 behandelt werden. Webhook-Payloads können Unicode-Zeichen enthalten.