Telegram Bot Webhook 502 トラブルシューティング：HTTPS 証明書、ファイアウォール、タイムアウト問題の完全ガイド

Telegram Bot が突然応答しなくなり、ユーザーメッセージが届かず、Bot のバックエンドログが空白の場合、問題はおそらく Webhook にあります。Bot API ログに 502 Bad Gateway や 504 Gateway Timeout が表示されている場合、Telegram サーバーが Bot のバックエンドに正常に接続できていない ことを意味します。これは越境カスタマーサポート、コミュニティ運営、自動化 Bot で最も一般的な障害の一つですが、調査手順は実際には決まっており、予測可能です。

この記事では、HTTPS 証明書、ファイアウォールルール、タイムアウト設定に関する段階的なチェックリストを提供します。独自の Bot サービスを使用している場合でも、TG-Staff コンソールを使用している場合でも、このガイドに従って迅速にサービスを復旧できます。

---

なぜ Telegram Bot は Webhook 502 エラーを返すのか？

Telegram Bot の Webhook メカニズムの本質は、ユーザーが Bot にメッセージを送信すると、Telegram サーバーが setWebhook で設定した URL に POST リクエストを送信することです。このリクエストが正常に受信され、200 OK が返されない場合、Telegram は数回の再試行後にエラーとしてマークします。

502 Bad Gateway は、アップストリームサーバー（あなたのバックエンド）にアクセスできないか、無効な応答が返されたことを示します。一般的な原因は次のとおりです：

• HTTPS 証明書が無効または期限切れ
• サーバーのファイアウォール/セキュリティグループがポート 443 を開放していない
• Telegram IP 範囲がブロックされている（クラウドプロバイダーまたは CDN ルール）
• バックエンド処理のタイムアウト（デフォルトの上限 30 秒）
• Webhook URL の設定ミス（HTTPS ではなく HTTP を使用しているなど）
• CDN/WAF による誤ったブロック、またはリバースプロキシの設定ミス

以下、手順を追って一つずつ確認します。

---

ステップ 1：HTTPS 証明書が有効か確認する

Telegram では、Webhook URL は信頼できる CA が発行した有効な HTTPS 証明書を使用する必要があります。自己署名証明書、期限切れ証明書、または不完全な証明書チェーンは、直接 502 エラーを引き起こします。

OpenSSL を使用した迅速な証明書確認

ターミナルで次のコマンドを実行し、サーバーのポート 443 の証明書情報を確認します：

openssl s_client -connect your-domain.com:443 -servername your-domain.com

出力に Verify return code: 0 (ok) が含まれている場合、証明書は有効です。20 (unable to get local issuer certificate) または 21 (unable to verify the first certificate) が返された場合、証明書チェーンが不完全です。

SSL Labs オンラインテストツール を使用して、より包括的なチェックを行うこともできます。

証明書の自動更新ソリューション（Let’s Encrypt）

証明書の期限切れは Webhook 502 の一般的な原因です。Certbot を使用した自動更新を推奨します：

sudo certbot renew --quiet

cron ジョブを設定して（1 日 2 回実行）、証明書が期限切れになる前に自動更新されるようにします。Nginx を使用している場合、Certbot は自動的に設定をリロードします。

---

ステップ2：ファイアウォールとネットワーク接続の確認

証明書が完全でも、サーバーの443番ポートに到達できない場合、Telegramは接続できません。

ポート到達性の確認（nc / telnet）

サーバーで次のコマンドを実行します：

nc -zv your-domain.com 443
# 或
telnet your-domain.com 443

接続が拒否されたりタイムアウトした場合、ファイアウォールまたはセキュリティグループのルールで443番ポートが許可されていません。

Telegram IPアドレス範囲がブロックされていないか確認

Telegramサーバーは固定IPアドレス範囲からWebhookリクエストを送信します。ファイアウォール、クラウドプロバイダーのセキュリティグループ、またはCDN/WAFルールで以下のアドレス範囲をブロックしていないか確認してください：

• Telegram公式IP範囲：https://core.telegram.org/resources/cidr.txt
• 特に 149.154.160.0/20 と 91.108.56.0/22 を許可

注意：一部のクラウドプロバイダーでは、デフォルトのセキュリティグループがすべてのインバウンドトラフィックを拒否するため、手動でルールを追加する必要があります。

---

ステップ3：Webhookリクエストのタイムアウトとサーバーパフォーマンスの確認

TelegramのWebhookリクエストのデフォルトタイムアウトは 30秒 です。バックエンドの処理ロジックに時間がかかりすぎる場合（例：データベースの遅いクエリ、外部API呼び出しの応答なし）、Telegramはタイムアウト後に再試行し、最終的に504を返します。

適切なタイムアウトと再試行戦略の設定

• バックエンドは15秒以内に200 OKを返すようにし、バッファを確保します。
• ビジネスロジックで長時間の処理が必要な場合（例：レポート生成）、まずユーザーに「処理中です。お待ちください」と返信し、バックグラウンドで非同期実行することを推奨します。
• デッドロックや無限ループを回避：コード内で解放されていないデータベース接続や無限ループがないか確認します。

TG-Staffコンソールで応答ステータスを確認

TG-StaffでBotを管理している場合、コンソールでWebhookのステータスとエラーログを直接確認できます：

1. app.tg-staff.com にログイン
2. 該当プロジェクトの「設定」ページに移動
3. Webhookステータスインジケーターを確認：「接続失敗」または「応答タイムアウト」と表示されている場合は、最初の3ステップを優先的にチェック

TG-Staffコンソールは、各Webhookリクエストの応答コードを記録し、タイムアウトか他のエラーかを迅速に特定するのに役立ちます。

---

ステップ4：Webhook URLの設定が正しいか確認する

多くの人が見落としがちな詳細：Webhook URLはHTTPSを使用する必要があり、スペルミスがあってはなりません。

setWebhook を呼び出す際は、以下を確認してください：

• URLが https:// で始まっていること（HTTPだと502エラーになります）
• パスが正しく、余分なスラッシュがないこと（例：https://example.com/ はデフォルトパスとして解釈される可能性があります）
• スペルミスがないこと（ドメイン名、サブドメイン、パスの大文字小文字を確認）

正しいコマンドの例：

https://api.telegram.org/bot<YOUR_TOKEN>/setWebhook?url=https://your-domain.com/webhook

---

ステップ5：Telegram APIが返す具体的なエラーコードを確認する

Telegramには getWebhookInfo メソッドがあり、Webhookが失敗した理由を正確に教えてくれます。

呼び出し：

https://api.telegram.org/bot<YOUR_TOKEN>/getWebhookInfo

返される結果の主要なフィールド：

フィールド	意味	一般的な値
last_error_date	最後のエラーが発生したタイムスタンプ	Unix時間
last_error_message	エラーの説明	”SSL_ERROR”, “NETWORK_ERROR”, “TIMEOUT”
max_connections	最大同時接続数	デフォルト40
pending_update_count	未処理メッセージ数	数値が大きいほど滞留が深刻

よくあるエラーの解釈：

• SSL_ERROR：証明書の問題（期限切れ、自己署名、チェーン不完全）
• NETWORK_ERROR：ファイアウォール、IPブロック、DNS解決の問題
• TIMEOUT：バックエンドの応答が30秒を超えている
• WRONG_URL：Webhook URLの形式が誤っている

---

ステップ6：よくある高度なシナリオとトラブルシューティングチェックリスト

CDNとリバースプロキシ

サイトでNginx/ApacheリバースプロキシやCDN（Cloudflareなど）を使用している場合は、以下を確認してください：

• Nginx設定：proxy_pass が正しいバックエンドポートを指していること、および proxy_set_header に Host、X-Real-IP などの必要なヘッダーが含まれていること
• Cloudflare：プロキシモードは Full (Strict) である必要があります。Flexible SSLを使用している場合、Telegramは証明書チェーンを検証できません
• WAFルール：誤ってTelegramのIP範囲をブロックしないようにしてください（ステップ2を参照）

IPv6とデュアルスタックの問題

サーバーがIPv4のみをサポートしているにもかかわらず、DNS解決がAAAAレコード（IPv6アドレス）を返す場合、TelegramがIPv6アドレスへの接続を試みて失敗する可能性があります。

解決策：

• DNSレコードからAAAAレコードを削除する
• またはサーバーがデュアルスタック（IPv4 + IPv6）をサポートしていることを確認する

---

よくある質問

質問： 証明書が有効なのに502エラーが返るのはなぜですか？ 回答： 考えられる原因として、ファイアウォールで443ポートが開放されていない、Telegram IP範囲がクラウドサービスのセキュリティグループでブロックされている、CDNプロキシモードの設定が間違っている（Full Strictを使用してください）、またはサーバーの応答が30秒のタイムアウトを超えている場合があります。手順2と手順3を順に確認してください。

質問： Telegram Bot Webhookの具体的なエラー情報を確認するにはどうすればよいですか？ 回答： Bot APIの getWebhookInfo メソッド（例：https://api.telegram.org/bot<YOUR_TOKEN>/getWebhookInfo）を呼び出すと、返された結果の last_error_message フィールドに「SSL_ERROR」や「NETWORK_ERROR」などの具体的なエラー理由が示されます。

質問： TG-Staffを使用する際、Webhookの状態を確認するにはどうすればよいですか？ 回答： TG-Staffコンソール（app.tg-staff.com）にログインし、該当プロジェクトの設定ページで「Webhook状態」インジケーターを確認します。異常が表示された場合は、コンソールが提供するエラーログを参照して迅速に特定できます。

質問： サーバーの応答時間が30秒を超えた場合はどうすればよいですか？ 回答： バックエンドの処理ロジックを最適化し（例：非同期タスクキューの使用）、200 OK応答が15秒以内に返されるようにすることを推奨します。長時間の処理が必要な場合は、まずユーザーに「処理中」のメッセージを返信し、バックグラウンドで続行することを検討してください。

質問： 自己署名証明書は使用できますか？ 回答： 使用できません。TelegramはWebhook URLに信頼できるCAが発行した有効なHTTPS証明書を要求します。Let’s Encryptの無料証明書をCertbotで自動更新することを推奨します。

---

Botサービスの迅速な復旧

Telegram Bot Webhookの502エラーに対処している場合、本記事のチェックリストに従えば通常15分以内に問題を特定できます。より簡単な管理方法が必要な場合は、TG-Staffを無料でお試しください：

• app.tg-staff.com で登録し、ワンクリックでWebhookを設定してBot状態を監視
• TG-Staffドキュメント のWebhook設定ガイドを参照
• @tgstaff_robot カスタマーサポートBotに連絡して技術支援を依頼

TG-Staffに組み込まれたWebhook状態検出とエラーログ機能により、証明書の期限切れ、タイムアウト、ネットワーク問題を迅速に発見でき、チームはトラブルシューティングではなく運営に集中できます。