Webhook のトラブルシューティング

Webhook の一般的なエラーを診断して解決する方法を学びます。

この記事の内容

欠落した webhook の配信

予期されていた Webhook 配信を受け取っていない場合は、配信が欠落しているポイントを特定する必要があります。

  1. Webhook 配信が発生すると予想されるイベントをトリガーします。 たとえば、Webhook が issues イベントにサブスクライブされているリポジトリ Webhook である場合、そのリポジトリでイシューを開くことができます。

  2. Webhook の最近の配信ログを確認します。 Webhook の種類ごとにこれを行う方法については、「webhookの配信の表示」を参照してください。

    最近の配信ログに、前の手順でトリガーした Webhook イベントに対応する配信が含まれていない場合、GitHub は配信を試行しませんでした。 原因を特定するには:

    1. 数分待ってからもう一度確認します。 Webhook の配信が表示されるまでに数分かかる場合があります。

    2. Webhook が構成されている場所でイベントをトリガーしたことを確認します。 たとえば、Webhook がリポジトリ webhook である場合は、Webhook が構成されているのと同じリポジトリでイベントをトリガーしたことを確認します。

    3. トリガーしたイベントに Webhook がサブスクライブされていることを確認します。 たとえば、問題を開いたときに Webhook 配信が予想される場合は、Webhook が issues イベントにサブスクライブされていることを確認します。

    4. Webhook がアクティブであることを確認します。 詳しくは、「Webhook を無効にする」をご覧ください。

    5. Webhook が OAuth app アクセス制限の影響を受けないことを確認します。 OAuth app を承認したユーザーの代わりに OAuth app によって Webhook が作成された場合、その Webhook は、OAuth app によるアクセスが制限されている組織またはリポジトリ Webhook である場合、自動的に無効になります。 詳細については、「OAuth アプリのアクセス制限について」 を参照してください。

    6. イベントが文書化された制限に達した可能性があるかどうかを確認します。 たとえば、一度に 3 つ以上のタグをプッシュした場合、そのプッシュに対して push イベントはトリガーされません。 各イベントの文書化された制限の詳細については、「Webhook のイベントとペイロード」を参照してください。

    7. githubstatus.com で Webhook の状態を確認します。

    最近の配信ログに、GitHub は配信を試行したが、配信は失敗しましたという配信エラーが発生したことを示す場合。 これは通常、サーバーに問題があるためです。 特定のエラーを解決するには、以下のセクションを参照してください。

  3. サーバーのログを確認します。 ログ内の情報は、Webhook 配信を処理するためにサーバーが実行するコードによって異なります。 サーバーの問題を診断するには、コードにログ ステートメントを追加することが必要な場合があります。

20 webhook を超えることはできません

イベントの種類ごとに、20 リポジトリまたは組織 webhook を作成できます。 さらに作成しようとすると、20 webhooks を超えることはできませんというエラーが表示されます。

20 Webhook を超える必要がある場合は、GitHub から Webhook を受信し、無制限の数の宛先 URL に転送するプロキシを実行できます。

URL ホスト localhost はサポートされていません

Webhook URL として localhost または 127.0.0.1 を使用することはできません。

テストのために Webhook をローカル サーバーに配信する場合は、webhook 転送サービスを使用できます。 詳細については、「webhookのテスト」を参照するか、https://smee.io/ を参照してください。

ホストに接続できませんでした

failed to connect to host エラーは、GitHub が Webhook 配信を試みたが、Webhook の URL を IP アドレスに解決できなかった場合に発生します。

ホスト名が IP アドレスに解決されるかどうかをチェックするには、nslookup を使用します。 たとえば、ペイロード URL が https://octodex.github.com/webhooks である場合は、nslookup octodex.github.com を実行できます。 ホスト名を IP アドレスに解決できなかった場合、nslookup コマンドはサーバーがホスト名を見つけることができないことを示します。

ネットワークに接続できませんでした

failed to connect to network エラーは、GitHub が Webhook を配信しようとしたときに、サーバーが接続を拒否したことを示します。

サーバーで、GitHub の IP アドレスからの接続が許可されていることを確認する必要があります。 GET /meta エンドポイントを使用して、GitHub の IP アドレスの現在の一覧を見つけることができます。 詳しくは、「メタデータ用 REST API エンドポイント」をご覧ください。 GitHub は IP アドレスを変更することがあるため、IP 許可一覧を定期的に更新してください。

タイムアウト

timed out エラーは、 10 秒の Webhook 配信中に、GitHub がサーバーから応答を受信しなかったことを示します。

Webhook デリバリーを受信してから 10 秒以内にサーバーが 2xx 応答を返すようにしてください。 サーバーの応答にそれ以上の時間がかかる場合、GitHub は接続を終了し、デリバリーが失敗したと見なします。

タイムリーに応答するために、Webhook ペイロードを非同期的に処理するキューを設定できます。 サーバーは、Webhook を受信したときに応答し、その後の Webhook デリバリーをブロックすることなく、バックグラウンドでペイロードを処理できます。 たとえば、Hookdeck などのサービスや、Resque (Ruby)、RQ (Python)、RabbitMQ などのライブラリを使用できます。

ピア証明書は与えられた CA 証明書で認証できません。

このエラーは、サーバーの証明書に関連した問題があることを示しています。 最も一般的な問題は次のとおりです。

  • サーバーは自己署名証明書を使用しています。
  • 接続が確立されたときに、サーバーが完全な証明書チェーンを送信していません。

問題の診断に役立つよう、SSL Labs から SSL サーバー テストを使用できます。 このサービスは、HTTPS の既定のポート (ポート 443) でのみ動作し、インターネットからアクセスできるサーバーでのみ機能します。

また、問題の診断に openssl を使用することもできます。 これを行うには、ターミナルで openssl s_client -connect HOST:PORT を実行します。 HOST をサーバーのホスト名に置き換え、PORT をポートに置き換えます。 たとえば、openssl s_client -connect example.com:443 のようにします。 問題を特定するには、出力内で verify error を探します。

無効な HTTP 応答です

invalid HTTP response エラーは、GitHub からの Webhook 配信に応答して、サーバーが 4xx または 5xx の状態を返したときに発生します。

2xx 状態を返すようにサーバーを構成する必要があります。 サーバーが 4xx または 5xx の状態を返した場合、GitHub は配信をエラーとして記録します。

Webhook の配信が順不同です

GitHub は、イベントが発生した順序とは異なる順序で Webhook を配信する場合があります。 イベントが別のイベントに関連していつ発生したかを知る必要がある場合、配信ペイロードに含まれるタイムスタンプを使用する必要があります。

Webhook の配信は即時ではありません

Webhook 配信は、配信されてから最近の配信ログに表示されるまでに数分かかる場合があります。 Webhook 配信が失敗したと判断する前に、数分待ってからもう一度確認してください。

ご自分のアカウントで Webhook 配信の急増が発生した場合、GitHub はアカウントへの配信率を一時的に調整する可能性があります。 Webhook デリバリーが GitHub によって遅くなる場合、影響を受ける各配信の throttled_at プロパティには、配信が調整されたときのタイムスタンプが表示されます。 REST API を使用してこれをチェックできます。「リポジトリ Webhook の配信を一覧表示する」を参照してください。

遅延を回避するには、アカウントに必要な Webhook イベントのみをサブスクライブし、配信の頻度を減らします。 「Webhook の使用に関するベスト プラクティス」をご覧ください。

署名の確認の失敗

Webhook シークレットを使用して、Webhookの配信がGitHub からであることを確認するには X-Hub-Signature-256 ヘッダーを使用する必要があります。 詳しくは、「Webhook 配信を検証する」をご覧ください。

ペイロードが GitHub から確実に取得されているが、署名の検証が失敗する場合:

  • Webhook のシークレットが構成されていることを確認します。 Webhook のシークレットを構成していない場合、X-Hub-Signature-256 ヘッダーは存在しません。 Webhook シークレットの設定について詳しくは、「webhookの編集」をご覧ください。
  • 正しいヘッダーを使用していることを確認します。 GitHub では、HMAC-SHA256 アルゴリズムを使用する X-Hub-Signature-256 ヘッダーを使用することをお勧めします。 X-Hub-Signature ヘッダーはHMAC-SHA1 アルゴリズムを使用し、従来の目的でのみ含まれています。
  • 正しいアルゴリズムを使用していることを確認します。 X-Hub-Signature-256 ヘッダーを使用している場合は、HMAC-SHA256 アルゴリズムを使用する必要があります。
  • 正しい webhook シークレットを使用していることを確認します。 Webhook シークレットの値がわからない場合は、Webhook のシークレットを更新できます。 詳しくは、「webhookの編集」を参照してください。
  • 検証の前にペイロードとヘッダーが変更されていないことを確認します。 たとえば、プロキシまたは負荷バランサーを使用する場合は、プロキシまたは負荷バランサーがペイロードまたはヘッダーを変更していないことを確認します。
  • 言語とサーバーの実装で文字エンコーディングが指定されている場合は、ペイロードをUTF-8として扱うようにしてください。 Webhook ペイロードには Unicode 文字を含めることができます。