ngrok・Cloudflare Tunnelでローカルを公開｜Webhook開発とデモ環境の作り方

「Stripeの決済完了Webhookを受け取る処理を書いたが、手元のPCには外から届かないので本番に上げるまで試せない」「LINE Botの動作確認のたびにステージングへデプロイしている」「取引先にデモを見せたいが、サーバーを用意するほどではない」。Webhookや外部連携の開発では、こうした"ローカルに外から届かない"問題が必ず出てきます。

この記事では、NATの内側にあるローカル環境に外部からのリクエストを届けるトンネリングの仕組みと、ngrok・Cloudflare Tunnel・localtunnelの違い、固定ドメインと認証の付け方、届いたリクエストの検査方法、公開時に気をつけるセキュリティ、自宅サーバー公開への応用までを解説します。Webhookの概念そのものは既知として、開発環境の作り方に集中します。

なぜローカルにWebhookが届かないのか｜トンネリングの仕組み

NATの内側からは「こちらから出る」しかできない

自宅やオフィスのPCはルーターのNATの内側にあり、プライベートIPしか持ちません。PCからインターネットへは出ていけますが、外部のStripeやGitHubが「あなたのPCの3000番」を宛先に指定することはできません。グローバルIPはルーターのものであり、ルーターはどのPCに転送すべきか知らないからです。ポート開放で対処する方法もありますが、集合住宅や法人回線ではCGNAT（キャリア側で二重にNATされる構成）のため開放自体が不可能なことも多く、なにより開発用途で常時ポートを開けるのは危険です。

トンネリングは「内から外へ張った接続」を逆向きに使う

ngrokなどのトンネリングツールは、この制約を発想の転換で回避します。

1. ローカルで動くクライアント（ngrokコマンド）が、ベンダーのサーバーへ外向きに常時接続を張る。NATは内から外への接続は許可するので問題なく通る。
2. ベンダーはあなた専用の公開URL（例：https://abc123.ngrok-free.app）を発行する。
3. StripeがそのURLにPOSTすると、ベンダーのサーバーが受け取り、すでに張ってある接続を逆向きに使ってローカルのクライアントへ転送する。
4. クライアントがlocalhost:3000のアプリに渡し、レスポンスを同じ経路で返す。

つまり公開URLで受けているのはベンダーのサーバーで、ローカル側は「常に外向きに接続している」だけです。ファイアウォールもルーターも何も変更せずに済むのはこのためです。

ngrok・Cloudflare Tunnel・localtunnelの比較

項目	ngrok	Cloudflare Tunnel	localtunnel
主な用途	開発・Webhookテスト	開発〜本番の常設公開	簡易テスト
固定ドメイン	無料枠で1つ固定可能、独自ドメインは有料	自分のCloudflare管理ドメインを無料で使える	希望サブドメインを指定可（保証なし）
認証・アクセス制限	Basic認証・OAuth・IP制限（プランによる）	Cloudflare Accessで社内SSO連携	簡易パスワード画面のみ
リクエスト検査	ローカルWeb UI（4040番）で再送も可能	ダッシュボードのログ	なし
セットアップ	コマンド1つ	ドメイン＋cloudflaredの設定が必要	npxで即時

使い分けの目安は「Webhookの試行錯誤ならngrok」「デモ環境や常設の社内ツール公開ならCloudflare Tunnel」「ちょっと見せるだけならlocaltunnel」です。ngrokは無料枠だと初回アクセス時に警告ページが挟まるため、Webhookの送信元によっては届かない場合があり、その際はリクエストヘッダー（ngrok-skip-browser-warning）の付与か有料プランで回避します。

ngrokでWebhookを受け取る手順

起動と固定ドメイン

# インストール（macOS）とトークン登録
brew install ngrok
ngrok config add-authtoken <YOUR_TOKEN>

# ローカルの3000番を公開（URLは起動のたびに変わる）
ngrok http 3000

# 無料枠で発行できる固定ドメインを使う（Stripe側に毎回登録し直さなくて済む）
ngrok http --url=your-name.ngrok-free.app 3000

# Basic認証をかけて公開
ngrok http --basic-auth="demo:s3cret" 3000

URLが毎回変わると、StripeダッシュボードやLINE Developersコンソールに登録したWebhook URLを都度書き換える手間が発生します。固定ドメインは最初に設定しておくと開発効率が大きく変わります。

リクエスト検査と再送

ngrokは起動時にローカルの http://127.0.0.1:4040 でWeb UIを提供します。届いたリクエストのヘッダー・ボディ・レスポンスをすべて確認でき、同じリクエストを再送（Replay）できます。Webhook開発ではこの再送機能が重要で、決済を何度も発生させずに、一度受け取ったペイロードでハンドラを修正しながら試せます。

# Stripe CLIならngrokなしでもローカルへ転送できる（Stripe専用）
stripe listen --forward-to localhost:3000/webhooks/stripe

# 署名検証は必ず実装する（Express + Stripeの例）
app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['stripe-signature'];
  let event;
  try {
    event = stripe.webhooks.constructEvent(req.body, sig, process.env.STRIPE_WEBHOOK_SECRET);
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }
  // event.type に応じた処理
  res.json({ received: true });
});

公開URLは誰でもPOSTできるため、Webhookハンドラは送信元の署名（Stripeのstripe-signature、LINEのx-line-signature、GitHubのX-Hub-Signature-256）を必ず検証してください。トンネル経由かどうかに関係なく、これは本番でも必須の実装です。

Cloudflare Tunnelで常設のデモ環境を作る

独自ドメインとアクセス制御

Cloudflare Tunnelは、Cloudflareで管理しているドメインのサブドメインをローカルやオフィス内のサーバーに割り当てられます。cloudflaredというクライアントを常駐させる点はngrokと同じですが、DNSとTLSがCloudflare側で完結し、Cloudflare Accessと組み合わせれば「Googleアカウントで社内ドメインのユーザーだけ通す」といった制御が無料枠で可能です。

# 認証とトンネル作成
cloudflared tunnel login
cloudflared tunnel create demo-app

# DNSレコード（demo.example.com → トンネル）を自動作成
cloudflared tunnel route dns demo-app demo.example.com

# ~/.cloudflared/config.yml
tunnel: demo-app
credentials-file: /Users/you/.cloudflared/<TUNNEL_ID>.json
ingress:
  - hostname: demo.example.com
    service: http://localhost:3000
  - hostname: api-demo.example.com
    service: http://localhost:8080
  - service: http_status:404     # 上記以外は404

# 起動（常設ならサービス登録）
cloudflared tunnel run demo-app
sudo cloudflared service install

取引先へのデモやプロトタイプ共有であれば、この構成で十分に「サーバーを借りずに公開する」ことができます。ドメイン側の設定はドメインとDNS設定のガイドを参照してください。

自宅サーバー・オフィスサーバー公開への応用

同じ仕組みで、自宅のRaspberry Piやオフィスの検証サーバーをポート開放なしに公開できます。オリジンのグローバルIPが外部に一切露出しないため、ルーターのポートフォワーディングより安全性が高い方法です。ただし「常設で公開する」以上、そのサーバーは本番相当の扱いが必要になります。OSの更新、Linuxサーバーのセキュリティ強化、Accessによるアクセス制限を前提にしてください。

公開時のセキュリティと、トラブル事例

開発用トンネルで気をつけること

• 開けっぱなしにしない：作業が終わったらトンネルを止める。固定ドメインは常時同じURLで到達できるため、放置すると開発中の脆弱な画面が公開状態になる
• 本番の認証情報を使わない：トンネル先のローカルアプリがステージングや本番のDBに繋がっていないか確認する
• デバッグ機能を露出させない：開発モードのエラーページやGraphQL Playgroundなどが公開URLから見える状態にしない
• 会社のセキュリティポリシーを確認：ベンダーのサーバーを経由する以上、リクエスト内容が第三者のインフラを通る。個人情報を扱う検証はダミーデータで行う

事例：Webhookは届いているのに処理が二重に走る

症状：ngrok経由で受けたStripeのWebhookで、注文確定メールが2通届く。ngrokのUIでは同じイベントのリクエストが2回記録されている。
原因：ハンドラの処理に時間がかかり、Stripe側のタイムアウト内に2xxを返せなかったため、Stripeがリトライした。ローカル環境はトンネルの往復分だけ遅延が増えるため、本番では起きなかった再送がローカルで顕在化した。
対処：Webhookハンドラは「受け取ったら即座に200を返し、重い処理はジョブキューに回す」構造に変更。あわせてイベントIDをDBに記録し、同じIDが来たら処理をスキップする冪等性チェックを入れた。これは本番でも必要な設計であり、ローカルで再現できたことでむしろ事前に対処できた例です。

まとめ

トンネリングは、NATの内側から外向きに張った接続を逆向きに使うことで、ポート開放なしにローカル環境へ外部リクエストを届ける仕組みです。Webhookの試行錯誤にはリクエスト検査と再送ができるngrok、デモや常設公開には独自ドメインとAccessで守れるCloudflare Tunnelが向いています。どちらを使う場合も、署名検証と冪等性はハンドラ側で必ず実装し、トンネルは使い終わったら閉じる、本番データに繋がない、という基本を守ってください。外部サービス連携の設計や検証環境の整備でお困りの際は、Harmonic Societyのシステム開発・インフラ支援にご相談ください。