なぜ UnifyPort webhook に ngrok が必要なのですか？

UnifyPort はイベントを公開 HTTPS URL に配信します。localhost:3000 で動くハンドラはインターネットから到達できないため、ngrok が両者を橋渡しします——コマンドを一つ叩けば https://*.ngrok-free.app URL が公開され、すべてのリクエストをローカルポートに転送します。

ngrok は HMAC 署名検証を壊しますか？

いいえ。無料 ngrok トンネルは上流で TLS を終端しますが、あなたのハンドラが受け取る body のバイト列は UnifyPort が署名したバイト列そのものです。署名検証は本番とまったく同じに動きます：hex(HMAC-SHA256(secret, timestamp + "." + body)) を計算し、X-Device-Signature と突き合わせるだけです。

本物の署名シークレットを使っても ngrok は安全ですか？

開発専用のシークレットを使うローカル開発なら、はい——トラフィックはエンドツーエンドで暗号化され、ngrok の inspector はローカルで動きます。staging 環境、デモ、本番相当のトラフィックでは、有料の予約済み ngrok ドメインを使うか、安定した無料ホスト名が手に入る Cloudflare Tunnel に切り替えてください。

← すべてのツール

私たちのメモ

ngrok で UnifyPort webhook をローカル開発する

UnifyPort はイベントを公開 HTTPS URL に配信します。あなたのハンドラが localhost にいるなら——大抵そうですが——トンネルが必要です。ngrok は長年私たちの第一選択肢でした。

ngrok.com を開く → UnifyPort webhook ドキュメント

ngrok が解決すること

コマンドを一つ叩けば、すべてのリクエストをローカルポートに転送する公開 HTTPS URL が得られます。通り抜けるトラフィックはすべて http://127.0.0.1:4040 のリクエスト inspector がキャプチャ——ヘッダ、ボディ、タイミング、replay ボタンつきで。この inspector があるからこそ、無料の代替トンネルが増えた今でも私たちは ngrok を使い続けています：本来ログを追いかけ続ける作業が、目線一つで済むレベルに圧縮されます。

UnifyPort ハンドラの 5 分セットアップ

ハンドラが port 3000 で待ち受けているとして：

1. ngrok http 3000——出力された https://*.ngrok-free.app URL をコピー。
2. POST /v1/webhook-endpoints で URL を登録——url を https://<your-tunnel>.ngrok-free.app/events にし、必要な subscribed_events を選択（イテレーション中は ["*"] で全部受けても可）。
3. ブラウザで http://127.0.0.1:4040 を開く。プロバイダ側からイベントをトリガー——Telegram の DM、WhatsApp のメッセージなど——届くのを眺めましょう。
4. replay ボタンで同じ配信を更新後のハンドラに再送。これがプロバイダ側で毎回イベントを焚き直すより速く ngrok を使う理由です。

ローカルで署名を検証する

無料 ngrok トンネルは上流で TLS を終端するため、あなたのハンドラがリクエストを見るときには body はすでに復号済み——まさに UnifyPort が署名したそれです。つまり署名検証は本番と同じ：hex(HMAC-SHA256(secret, timestamp + "." + body)) を計算し、X-Device-Signature ヘッダと突き合わせる。コードを書く前に手で確かめたいときは、私たちの CyberChef レシピでブラウザ上の同じアルゴリズムを試せます。

ngrok が最適解でなくなるとき

staging や demo 環境。無料 URL は再起動ごとに変わり、長期設定が壊れます。有料の予約ドメインに上げるか、Cloudflare Tunnel に乗り換えて無料の固定ホスト名を入手しましょう。
高頻度の負荷テスト。無料 ngrok のスロットリングはきつい。アップグレードするか、実環境でハンドラを動かしてください。
webhook 専用、他に HTTP トラフィックがないワークフロー。smee.io の方が軽い——バイナリ不要で、クライアントスクリプトだけ。

よくある質問

なぜ UnifyPort webhook に ngrok が必要なのですか？: UnifyPort はイベントを公開 HTTPS URL に配信します。localhost:3000 で動くハンドラはインターネットから到達できないため、ngrok が両者を橋渡しします——コマンドを一つ叩けば https://*.ngrok-free.app URL が公開され、すべてのリクエストをローカルポートに転送します。
ngrok は HMAC 署名検証を壊しますか？: いいえ。無料 ngrok トンネルは上流で TLS を終端しますが、あなたのハンドラが受け取る body のバイト列は UnifyPort が署名したバイト列そのものです。署名検証は本番とまったく同じに動きます：hex(HMAC-SHA256(secret, timestamp + "." + body)) を計算し、X-Device-Signature と突き合わせるだけです。
本物の署名シークレットを使っても ngrok は安全ですか？: 開発専用のシークレットを使うローカル開発なら、はい——トラフィックはエンドツーエンドで暗号化され、ngrok の inspector はローカルで動きます。staging 環境、デモ、本番相当のトラフィックでは、有料の予約済み ngrok ドメインを使うか、安定した無料ホスト名が手に入る Cloudflare Tunnel に切り替えてください。