localhost の Telegram ボットと Mini Apps: setWebhook、Secret-Token ヘッダー、そして新しい origin チェック
localhost で Telegram ボットと Mini Apps を実行する: setWebhook の設定、secret-token ヘッダーの検証、Bot API 10.2 の origin チェックを通過させる。安定したトンネルのヒント。

Quick answer
localhost 上の Telegram ボットと Mini Apps: Webhook ガイド 2026: webhook testing answer
For local webhook testing, run your app locally, expose it with a public HTTPS tunnel, and paste the stable callback URL into the provider dashboard.
How do I test webhooks on localhost?
Start your local server, open a public HTTPS tunnel to that port, configure the provider webhook URL, and inspect events in your local logs.
Why does a stable webhook URL matter?
Stable URLs prevent provider dashboards from needing manual callback updates every time you restart a tunnel.
Telegram は公開 HTTPS アドレスにのみアップデートを配信でき、localhost はそれには該当しません。2026年7月20日以降、Mini Apps には2つ目の制約があります。Telegram は Mini App の自ドメインと異なる origin から呼び出された場合、Mini App のメソッドをブロックします。これら2つの事実が相まって、あなたのトンネル URL は使い捨ての詳細ではなく、設定の第一級の要素になります。
このガイドは、ローカルマシンに対して Telegram ボットと Mini App を開発する方法を扱います:
setWebhookで webhook を登録する- secret-token ヘッダーを使ってリクエストを認証する
- 未知の更新フィールドを処理して再試行を発生させない
- Mini App の
initDataを検証する - 新しい origin check が開発セットアップに与える影響を理解する
Bot API 10.2 で何が変更されたか(およびそれ以降のリリースで追加されたもの)
Telegram は Bot API 10.2 on July 14, 2026 をリリースしました。公式のチェンジログによると、そのリリースは Mini App のセキュリティを高め、元の Mini App ドメインとは異なる origins からの Mini App メソッドの呼び出しを許可しなくなりました。この保護は 2026年7月20日に全ての Mini Apps に自動的に有効化されました。Bots は BotFather Mini App からオプトアウトすることができます。オプトアウトとは、Mini App に信頼できないサイトへのリンクがないことを保証する責任を負うことを意味します。Telegram の BotNews チャンネルはこの変更を警告として伝えました:Mini App 内のリンクから開かれた外部ウェブサイトはデフォルトで Mini App メソッドを使用できなくなります。
10.2 の他の追加機能も知っておくと役立ちます。 webhook ペイロードに現れるためです:
- エフェメラルメッセージ(Ephemeral messages):新しい編集・削除メソッドと、
Messageのreceiver_userおよびephemeral_message_idが追加。 - リッチメッセージ(Rich messages):
InputRichMessageにblocksとmediaフィールドが追加。 - コミュニティ(Communities):新しい
Community型、community_chat_addedおよびcommunity_chat_removedサービスメッセージ、ChatFullInfoにcommunityフィールド。 - サブスクリプション(Subscriptions):
Updateに新しいトップレベルのsubscriptionフィールドが追加され、BotSubscriptionUpdatedオブジェクトを保持。
Bot API はそれ以降も動き続けています:
- Bot API 10.3 (August 24, 2026):
- リッチメッセージ内のボタン
- 無効化されたインラインボタン
- エフェメラルメッセージのパラメータを 1 つの
ephemeral_message_parametersオブジェクトに統合 - ストリームド drafts 用のネイティブ Stop ボタン
Updateに新しいstopped_message_generationフィールド
- Bot API 10.4 (November 9, 2026):
- HTML ウィジェット(
sendWidget、sendSharedWidget、answerWidgetQuery、editMessageWidgetData、editSharedWidgetData) - TON ウォレットカードと送金サービスメッセージ
- ボタン押下によりトリガーされるエフェメラル返信
- ライブラリのリリースノートによれば、新しい
widget_queryおよびshared_widget_query更新タイプ
- HTML ウィジェット(
これらの 10.2–10.4 の発表は、setWebhook や secret-token ヘッダーの挙動を変えません。Update オブジェクトは依然としてトップレベルのフィールドを追加し続けており、Step 3 が重要になる理由です。
なぜ localhost で Telegram ウェブフックは機能しないのか
ウェブフックは Telegram のサーバーからあなたの URL へ送られる HTTPS POST です。Telegram は http://localhost:3000 に到達できないため、機器へ転送する公開 HTTPS エンドポイントが必要です。Telegram のドキュメント上の要件は次のとおりです:
- URL は HTTPS でなければならない。
- サポートされるウェブフックのポートは 443, 80, 88, 8443。
- ウェブフックが設定されている間、
getUpdatesで更新を受け取ることはできません。 - Self-signed 証明書は
certificateパラメータを介して公開証明書をアップロードすることを要求しますが、開発時にはほとんど価値がありません。 - Hookdeck の Telegram の webhook ガイドの要約によると、配信は IPv4 のみで TLS 1.2 以降が必要です。
- 未配信の更新は 24 時間を超えて保存されません。
トンネルはこれらすべてを一度に満たします。443 ポートで有効な証明書を持つ公開ホスト名を提供し、ローカルの 3000 のようなポートへトラフィックを転送します。
ボット側だけの例外があります。オープンソースの telegram-bot-api サーバーをローカルで実行している場合、Telegram はボットが HTTP webhook URL、任意のローカル IP アドレス、任意のポートを使用できると文書化しています。これにより webhook 配信のためのトンネルは不要になります。ただし、電話から Mini App をアクセスできるようにはなりません。Telegram クライアントはまだ Mini App URL を読み込む必要があるからです。
各ボットには正確に1つの webhook URL があります。再度 setWebhook を呼ぶと、それが置換されます。実験が本番トラフィックを再ルーティングしないように、BotFather を通じて作成した別の開発ボットを使用します。
ステップ 1: setWebhook で webhook を登録する
ローカルサーバを起動し、トンネルを起動して、公開 URL を登録します:
curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-subdomain.example.com/telegram/webhook",
"secret_token": "'"$TELEGRAM_WEBHOOK_SECRET"'",
"allowed_updates": ["message", "callback_query"],
"drop_pending_updates": true
}'
実際に使用するパラメータ:
| Parameter | What it does |
|---|---|
url |
POST ごとに 1 つの JSON 文字列化された Update を受信する HTTPS URL。空文字列は webhook を削除します。 |
secret_token |
リクエストごとにヘッダーとしてあなたに返される秘密。1–256 文字。 |
allowed_updates |
受け取るアップデートのタイプ。空のリストは chat_member, message_reaction および message_reaction_count を除くすべてのタイプを意味します。省略すると前の設定が保持されます。 |
max_connections |
配信の最大同時 HTTPS 接続数、1–100、デフォルトは 40。 |
drop_pending_updates |
バックログを破棄します。新しい URL にボットを移動する場合に有用。 |
ip_address |
DNS 解決の代わりに使用する固定 IP。 |
certificate |
自己署名設定の公開証明書(ファイルとしてアップロード)。 |
開発時に時間を節約する二つの習慣:
- URL を変更するときは
drop_pending_updatesを設定して、ローカルサーバーが古いメッセージで氾濫しないようにする。 - 配送が止まったら
getWebhookInfoを呼び出します。現在の URL、pending_update_count、last_error_date、last_error_messageおよび有効なallowed_updatesを報告します。
allowed_updates の変更は、呼び出し前に作成されたアップデートには適用されないため、いくつかの不要なアップデートがまだ到着することがあります。
curl "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getWebhookInfo"
ポーリングに戻すには、deleteWebhook を呼び出します。
ステップ 2: secret-token ヘッダーを検証する
setWebhook に secret_token を渡すと、Telegram はすべての webhook リクエストの X-Telegram-Bot-Api-Secret-Token ヘッダーにそれを含めます。トークンは 1–256 文字で、使用できる文字は A-Z、a-z、0-9、_ および - のみです。
秘密を設定しない場合、URL を知っている誰でもリクエストを偽造できるため、Telegram はヘッダーを送信しません。
この仕組みは「署名ではなく共有された秘密」です。本文自体で何かを計算することはなく、秘密が漏れると攻撃者が回転させるまでリクエストを偽造できます。回転は簡単で、新しい値で再度 setWebhook を呼び出します。Hookdeck のガイドは Telegram の公開ソース範囲(149.154.160.0/20 および 91.108.4.0/22)を二次レイヤとして挙げ、変更される可能性があるとしています。
Minimal Express ハンドラ:
import express from "express";
import crypto from "node:crypto";
const SECRET = process.env.TELEGRAM_WEBHOOK_SECRET;
if (!SECRET) throw new Error("TELEGRAM_WEBHOOK_SECRET is not set");
const app = express();
app.use(express.json());
function secretMatches(received) {
const a = Buffer.from(received ?? "");
const b = Buffer.from(SECRET);
return a.length === b.length \u0026\u0026 crypto.timingSafeEqual(a, b);
}
app.post("/telegram/webhook", (req, res) => {
if (!secretMatches(req.get("x-telegram-bot-api-secret-token"))) {
return res.sendStatus(401);
}
res.sendStatus(200); // acknowledge, then process
handleUpdate(req.body).catch(console.error);
});
app.listen(3000);
3 つの詳細はコピーしておく価値があります:
- 比較は定数時間で行われます。
- チェックは本文を処理する前に実行されます。
- 秘密が設定されていない場合、ハンドラは拒否します。
Telegram は応答タイムアウトを公開していないため、配信を遅延させないようにしてください。アップデートを保存してから処理を開始し、200 を返してから処理します。200 を返してからクラッシュすると更新は失われるため、受信時点で保存しておきます。
ステップ 3: 未知のフィールドを許容して Telegram の再送を回避する
Telegram は 2xx 以外の応答をすべて配信失敗とみなし、再送を行い、いわゆる「合理的な試行回数」を超えると諦めます。厳密なパーサーにはこれが重大な影響を与えます。ハンドラが未知のフィールドを含む更新を受け付けない場合、Telegram はそれを再送信し続け、ログには同じ失敗が埋まります。
Update には update_id が含まれ、最大でもう1つのフィールドを持つことができます。これらのフィールドは増え続けます: managed_bot、guest_message、subscription、stopped_message_generation、そして 10.4 では widget クエリ。
未知のキーでデコードが失敗するデコーダは、あなたのボットに問題がなくてもエラーを返し始める可能性があります。実用的なルール:
- 知っているフィールドを解析し、残りは無視する。 TypeScript の Zod では webhook スキーマで
.strict()を避けてください。Go ではデコーダでDisallowUnknownFieldsを避けてください。Rust の serde では、Telegram の型にdeny_unknown_fieldsを追加しないでください。 - 処理しない更新には 200 を返す。 未対応の更新はエラーではありません。
- 未知の更新種別を低レベルでログ に記録して、新機能に気づくと同時に配信を壊さないようにします。
update_idで重複を排除。 Telegram はこれを重複更新を無視し順序を回復する方法として文書化しています。1 週間更新がない場合、次の ID は連続ではなくランダムに選択されるため、連番を前提にしないでください。- Telegram ライブラリを固定して、アップグレード前にリリースノートを読む。 ライブラリは新しい Bot API バージョンをどれだけ早くカバーするかが異なり、知らないアップデートタイプを黙って削除するものもあります。
async function handleUpdate(update) { if (update.message) return onMessage(update.message); if (update.callback_query) return onCallback(update.callback_query); const kind = Object.keys(update).find((k) => k !== "update_id"); console.info("unhandled update kind:", kind); }
allowed_updates を二次レイヤとして使用します。取り扱うタイプだけを購読することで、関連のないイベントが到達するのを防ぎます。
ステップ 4: localhost から Mini App を提供する
Mini App は Telegram のインアプリブラウザ内で動作するウェブページで、クライアントと window.Telegram.WebApp を介して通信します。開発時にはトンネル URL を指すようにします:
- フロントエンドの開発サーバをローカルポートで起動。
- トンネルを起動して公開 HTTPS のホスト名をメモ。
- Mini App が起動する場所すべてでその URL を設定。Telegram は複数のルートを文書化しています:
web_appの inline または keyboard ボタン、BotFather の Bot ボタン (/setmenubutton)、Bot Settings → Menu Button、BotFather の Main Mini App、https://t.me/botusername/appname形式の直接リンク。 - Telegram 内のボットを開き、Mini App を起動。
ホスト名を表示されるすべての場所で同一に保ちます。以下の origin check は、それ以上の整頓性を要求します。
本番用の Mini Apps は HTTPS 経由で提供されます。トンネルはそれを実現します。Telegram の別個のテスト環境は例外です。テスト環境は独自のアカウントとボットを使用しており、ドキュメントはそこでプレーンな HTTP の Mini App リンクを許可しています。https://api.telegram.org/bot<token>/test/METHOD_NAME 経由で呼び出します。
以下のフレームワークの注意点が繰り返し現れます:
- ホストチェック。Vite の開発サーバは
Hostヘッダーがlocalhost、.localhostサブドメイン、あるいは IP アドレスであるリクエストにのみ応答します。そうでなければ「Blocked request. This host is not allowed.」と返します。 tunnel のホスト名をserver.allowedHostsに追加します。先頭のドットはサブドメインをマッチします。allowedHosts: trueを設定しないでください。そうすると任意のHostヘッダーを受け付け、開発サーバーを DNS リバインディングに開放します。 - ホットリロード。HMR WebSocket もトンネルを通過する必要があります。HTTPS トンネルの背後では
server.hmr.clientPortを 443 に設定する必要がある場合があります。Strapi のガイドにこれを推奨していますが、あなたの設定で試してみてください。
Telegram クライアント内でデバッグするには、次のオプションが記載されています:
- iOS: Settings アイコンを 10 回タップして Allow Web View Inspection を有効にし、Safari の Develop メニューを使います。
- Android: Telegram のデバッグ設定で WebView Debug を有効にし、
chrome://inspect/#devicesを開きます。 - Desktop: Windows/Linux のベータには実験的な WebView 検査、macOS のベータには「Debug Mini Apps」オプションがあります。
initData をサーバーで検証する
Mini App が開くと、window.Telegram.WebApp.initData は署名付きのクエリ文字列を含みます。キーボードボタンや inline モードから起動された場合は空になります。クライアント上の initDataUnsafe や任意のユーザーオブジェクトを信頼してはいけません。生の文字列をバックエンドに送信し、Telegram の公開アルゴリズムで検証します:
hashフィールドを削除します。その他の受信フィールドはすべて残します(第三者検証用のsignatureを含む)。- 残りの
key=valueペアをキーでソートし、改行で連結します()。 - 秘密鍵を計算します:ボットトークンを用いた HMAC-SHA256、キーとして定数文字列
WebAppDataを使用。 - その秘密鍵でデータチェック文字列の HMAC-SHA256 を計算し、16進表現で出力します。
- それを constant time で
hashと比較し、auth_dateの古い値を拒否します。import crypto from "node:crypto"; function verifyInitData(initData, botToken, maxAgeSeconds = 3600) { const params = new URLSearchParams(initData); const hash = params.get("hash"); params.delete("hash"); const checkString = [...params.entries()] .sort(([a], [b]) => (a < b ? -1 : 1)) .map(([k, v]) => `${k}=${v}`) .join("\n"); const secret = crypto.createHmac("sha256", "WebAppData").update(botToken).digest(); const expected = crypto.createHmac("sha256", secret).update(checkString).digest("hex"); const valid = hash && hash.length === expected.length && crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(expected)); const fresh = Date.now() / 1000 - Number(params.get("auth_date")) <= maxAgeSeconds; return Boolean(valid && fresh); }
Telegram は auth_date をチェックするだけで十分だと述べています。1時間のウィンドウはあなたの選択です。第三者がボットトークンなしでデータを検証する必要がある場合、Telegram は Ed25519 の signature フローを提供しており、それはボットの数値 ID と Telegram の公開鍵を使います。
新しい Mini App origin チェックの解説
2026年7月20日以前、Mini App の webview 内で開かれた任意のページは Telegram.WebApp.* のようなメソッド(close()、expand()、メインボタン、sendData() など)を呼び出せました。現在、それらの呼び出しは Mini App の自ドメインからのみ許可されています。Telegram の changelog はこれを「original Mini App domain」と呼びます。第三者のドキュメントでは BotFather に Bot を登録したドメインとして説明されています。
Leadgram の変更解説による実務的な意味は次のとおりです:
- Mini App のドメイン上のページ は引き続き機能します。
- 別ドメイン上のページ(オファーページ、決済ページ、認証ページなど)は Mini App 内から開かれていても Mini App メソッドを呼ぶことができなくなります。AdsGram の解説は iframe ベースの設定や複数ドメイン構成にも影響があると指摘しています。
- その他はすべて動作します。 ウェブビュー内の第三者ページは開き、通常のリンク、HTTP リダイレクト、
t.meリンク、サーバーサイド呼び出しは影響を受けません。唯一ブロックされるのは、別ドメインから Telegram の Mini App メソッドを呼ぶことです。ページから別の API ドメインへ直接fetchを行うのは別の問題です。 - 登録済みドメインは実在のものにする。 Leadgram は、Mini App の URL がリダイレクト、トラッカー、ショートナーを指している場合、Mini App がそのドメインに登録されると警告します。その結果、実際のドメインの Telegram コールがブロックされます。登録を最終目的地に向けてください。
localhost とトンネルに関する意味
このルールはホスト名に関するものです。これらの結論がそれに続きます:
- ランダムで回転する URL は、あなたのページを提供するホスト名が登録済みのものと異なるため、すべての場所を更新するまで Mini App メソッドが失敗します。
- 安定したサブドメイン を使えば、Mini App origin を一度だけ登録できます。BotFather の URL、あなたのフロントエンドが動作する URL、ウェブフックの URL は再起動をまたいでも同じままです。
- 分離された環境 は、それぞれ別のホスト名を用意するのが望ましく、環境ごとに別の開発ボットを用意すると良いです。
Telegram.WebAppを呼ぶすべてのページを登録済みドメイン上に保ってください。
開発時に Mini App メソッドが突然機能しなくなった場合のデバッグチェックリスト:
- ページの origin を登録した URL と比較します。サブドメインを含めて完全に一致していますか?
- 登録済みの URL とページの間に中間リダイレクトがないか確認します。
- コード内で
Telegram.WebAppを検索し、それらのページを提供しているドメインを確認します。Leadgram はDevTools を開いた状態で Telegram Desktop または web.telegram.org でユーザーの経路を辿ることを提案しています。 - iframe や他のドメインへのナビゲーション(認証プロバイダや決済ページなど)を探します。
- トンネルのホスト名が最後に登録した時から変更されていないことを確認します。
もし外部のページが close() や openLink() のみを呼ぶ場合、Leadgram の提案する対処法は、それを通常の https://t.me/... リンクまたはリダイレクトに置き換えることです。
オプトアウトすべきですか?
BotFather Mini App では保護を無効化できますが、Telegram の文言は警告的です。これを行うと、Mini App が信頼できないサイトへのリンクを持たないことを保証する責任を負うことになります。オプトアウトはウェブビュー内の任意のページがアプリを操作できる旧い挙動を復元します。 origin mismatch が根本的な問題である場合、開発環境を機能させるためにオプトアウトを選ぶのは適切な解決策ではありません。不一致を修正し、保護を維持し、Mini App が遷移できるすべてのページを自分でコントロールできるケースに限りオプトアウトを検討してください。
トンネルの選択: なぜ安定したサブドメインが実用的な解決策なのか
この記事の Telegram 設定はすべて URL に紐づいています。Webhook エンドポイント、Mini App のドメイン、そして Telegram がページが Mini App メソッドを呼ぶときに照合する origin です。再起動のたびに URL が変わると、3つすべてを毎回再登録する必要があります。1つの更新を忘れると、サイレントなウェブフックや昨日は動作していた Mini App のメソッドが今日動作しなくなる、という混乱を招くことがあります。
文書化された無料オプションが提供するもの:
| オプション | ホスト名 | 注記 |
|---|---|---|
| ngrok Free | アカウントごとに割り当てられた開発用ドメイン、エージェントを再起動しても変わらない | ngrok のドキュメントに基づく制限: 1 GB のデータ転送、月あたり 20,000 HTTP リクエスト、最大 3 つのオンラインエンドポイント。無料エンドポイントにはタイムアウトなし。 |
| Cloudflare Quick Tunnel | 毎回ランダムな trycloudflare.com ホスト名 |
アカウント不要だが Cloudflare は「テスト目的」としてラベル付けしており、200 の同時リクエスト制限と Server-Sent Events はなし。 |
| Cloudflare named tunnel | 自分のドメイン上のホスト名を自分で選択 | Cloudflare アカウントとドメインが必要。 |
ngrok のインタースティシャルに注意。無料プランでは、ngrok は HTML ブラウザトラフィックの前にインタースティシャルページを表示します。これが API やプログラム的アクセスに影響を与えないとngrokは言いますが、ウェブビュー内で読み込まれる Mini App ページは HTML ブラウザトラフィックなので、ユーザーは警告ページを見るかもしれません。ngrok はそれを取り除く二つの方法を文書化しています:有料プランへアップグレードする、またはクライアントが skip ヘッダーを送るか非標準の User-Agent を送る方法です。ヘッダー経由の方法は、Telegram のwebviewが読み込むページには扱いづらいです。
他のトンネルサービスは、無料または有料の階層で安定したサブドメインを提供します。サブドメインの持続性、セッション長、ブラウザ警告ページの現在の条項をプロバイダの最新情報で確認してから依存してください。
セットアップチェックリスト
- BotFather で専用の開発ボットを作成します。
- 安定したホスト名を持つトンネルを選び、そのホスト名を Webhook と Mini App の両方に使用します。
- 一度だけ
setWebhookを呼び出し、secret_tokenと絞り込んだallowed_updatesを設定します。 - Mini App の URL を同じホスト名に登録します。リダイレクトは避けます。
- 開発サーバーのホストチェックでそのホスト名を許可します。
- サーバーサイドで secret-token ヘッダーと
initDataを検証します。 - 未知の更新フィールドを無視してログに記録し、
update_idで重複排除します。 - 配送が止まったら、まず
getWebhookInfoを確認します。
よくある質問
Telegram がウェブフックを送信できるポートはどれですか?
443、80、88、8443。トンネルはポート 443 を公開し、ローカルの任意のポートにフォワードします。
ウェブフックがエラーを返した場合はどうなりますか?
Telegram は 2xx 以外の応答を失敗とみなし、リトライします。合理的な試行回数を超えると終了します。予期しない入力でエラーとなるエンドポイントは、繰り返し配信を引き起こす可能性があります。
トンネルを飛ばして getUpdates を使えますか?
ボットのロジックの場合は可能です。ただしウェブフックが設定されていない場合のみです。Mini App には Telegram クライアントが読み込める URL が必要で、公開 HTTPS のホスト名が必要です。例外はテスト環境とローカルの Bot API サーバーです。
秘密のトークンは必須ですか?
いいえですが、秘密がなければリクエストのどこにも Telegram を特定できる情報が含まれず、トンネルの URL を知っている人が偽造アップデートを送ることができます。
Bot API 10.2 は最新バージョンですか?
いいえ。Bot API 10.3(2026年8月24日)と 10.4(2026年11月9日)がそれ以降にリリースされています。ここで説明しているウェブフックと Mini App origin の挙動は引き続き適用されます。
出典
- Telegram Bot API changelog
- Telegram Bot API reference: setWebhook, getWebhookInfo, Update, local Bot API server
- Telegram Mini Apps documentation: initData validation, testing, debugging
- BotNews channel on Telegram (10.2 origin warning, 10.3 and 10.4 announcements)
- Telegram Bot API 10.2 migration guide, DEV Community
- Guide to Telegram webhooks, Hookdeck
- Mini App origin lockdown, Leadgram docs
- Telegram Mini App development mistakes, AdsGram
- go-telegram/bot Bot API 10.4 support (widget update types)
- ngrok free plan limits
- Cloudflare Quick Tunnels
- Cloudflare Tunnel getting started (quick tunnel limits)
- Opening your dev server to the public, Quasar
- Fixing “Blocked request” in Strapi 5 (HMR clientPort)
Related InstaTunnel pages
Continue from this article into the most relevant product guides and workflows.
Related Topics
Keep building with InstaTunnel
Read the docs for implementation details or compare plans before you ship.