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

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

## 未配信の Webhook

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

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

2. Webhook の最近の配信ログを確認します。 Webhook の種類ごとにこれを行う方法については、「[Webhook配信の確認](/ja/enterprise-server@3.22/webhooks/testing-and-troubleshooting-webhooks/viewing-webhook-deliveries)」を参照してください。

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

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

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

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

   4. Webhook がアクティブであることを確認します。 詳しくは、「[Webhook を無効にする](/ja/enterprise-server@3.22/webhooks/using-webhooks/disabling-webhooks)」をご覧ください。

   5. Webhook が OAuth app アクセス制限の影響を受けないことを確認します。 OAuth app を認証するユーザーの代わりに、OAuth app が Webhook を作成した場合、Webhook が OAuth app によって制限されたアクセスを付与された組織の組織 Webhook またはリポジトリ Webhook、その Webhook は、自動で無効になります。 詳細については、GitHub Free の文書内の「[OAuth アプリのアクセス制限について](/ja/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions)」をご覧ください。

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

   7. [githubstatus.com](https://www.githubstatus.com/) で Webhook の状態を確認します。

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

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

## Webhook の数は 250 を超えることはできません

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

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

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

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

テストのために Webhook をローカル サーバーに配信する場合は、webhook 転送サービスを使用できます。 詳細については、「[webhookのテスト](/ja/enterprise-server@3.22/webhooks/testing-and-troubleshooting-webhooks/testing-webhooks)」を参照するか、<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 コマンドはサーバーがホスト名を見つけることができないことを示します。

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

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

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

サーバーが GitHub の IP アドレスからの接続を許可するように確認してください。
`GET /meta` エンドポイントを使用して、GitHub の IP アドレスの現在の一覧を見つけることができます。 詳しくは、「[メタデータ用 REST API エンドポイント](/ja/enterprise-server@3.22/rest/meta/meta#get-github-meta-information)」をご覧ください。 GitHub は IP アドレスを変更することがあるため、IP 許可一覧を定期的に更新してください。

## タイムアウト

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

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

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

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

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

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

問題の診断に役立つよう、SSL Labs から [SSL サーバー テスト](https://www.ssllabs.com/ssltest/analyze.html)を使用できます。 このサービスは、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 シークレットを使用して、Webhookの配信がGitHub からであることを確認するには `X-Hub-Signature-256` ヘッダーを使用する必要があります。 詳しくは、「[Webhook 配信を検証する](/ja/enterprise-server@3.22/webhooks/using-webhooks/validating-webhook-deliveries)」をご覧ください。

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

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