點解我用 UnifyPort webhook 要用 ngrok？

UnifyPort 將事件投遞去一個公網 HTTPS URL。跑喺 localhost:3000 嘅 handler 喺互聯網度連唔到，所以 ngrok 將兩邊駁起——一條命令就發佈一個 https://*.ngrok-free.app URL，將每個 request 轉去你嘅本地 port。

ngrok 會唔會搞壞 HMAC 簽章驗證？

唔會。ngrok 免費版 tunnel 喺 upstream 解 TLS，但你 handler 收到嘅 body bytes 正正就係 UnifyPort 簽嗰啲 bytes。簽章驗證同 production 一模一樣：計 hex(HMAC-SHA256(secret, timestamp + "." + body))，再同 X-Device-Signature 對。

用真嘅 signing secret 嚟用 ngrok 安唔安全？

本地開發用淨係開發用嘅 secret，係安全嘅——流量端到端加密，ngrok 個 inspector 又喺本地跑。但 staging 環境、demo、或者 production 級流量，就最好用付費 reserved ngrok domain，又或者轉去 Cloudflare Tunnel，會畀返個固定免費 hostname 你。

← 所有工具

我哋啲筆記

用 ngrok 做 UnifyPort webhook 嘅本地開發

UnifyPort 將事件投遞去一個公網 HTTPS URL。如果你嘅 handler 跑喺 localhost——大多數日子都係——你就需要一條 tunnel。ngrok 多年嚟都係我哋嘅 default 選擇。

打開 ngrok.com → UnifyPort webhook 文檔

ngrok 解決乜嘢

一條命令就有個公網 HTTPS URL，把每個 request 轉去本地某個 port。所有經過嘅流量都會畀 http://127.0.0.1:4040 嘅 inspector 捕獲——headers、body、時序、replay 掣樣樣齊。呢個 inspector 就係我哋到而家都仲用 ngrok 嘅原因，就算有唔少免費 tunnel 替代品都好：佢將原本要邊打 log 邊追嘅嘢壓縮成「望一眼」。

UnifyPort handler 嘅五分鐘設定

假設 handler 聽住 3000 port：

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（iterate 緊嘅時候可以用 ["*"] 全收先）。
3. Browser 開 http://127.0.0.1:4040。從 provider 嗰邊觸發事件——一條 Telegram 私訊、一條 WhatsApp message——望住佢落嚟。
4. 用 replay 掣將同一條投遞重新發畀改咗 code 嘅 handler。呢個就係 ngrok 比每次改 code 都要去 provider 嗰邊重新觸發事件快嘅原因。

本地驗證簽章

ngrok 免費版 tunnel 喺 upstream 已經解咗 TLS，所以你嘅 handler 收到 request 嗰陣 body 已經係明文——正正係 UnifyPort 簽嘅嗰份。即係簽章驗證同 production 一樣：計 hex(HMAC-SHA256(secret, timestamp + "." + body))，同 X-Device-Signature header 對。想加 code 之前先手動確認一次嘅話，可以行我哋嘅 CyberChef 教學——同一個算法喺 browser 度跑一次。

ngrok 唔再係最好答案嘅時候

Staging 或者 demo 環境。免費版 URL 每次 restart 都換，長期配置會中斷。要嘛上付費版用 reserved domain，要嘛換 Cloudflare Tunnel，免費攞個固定 host。
高頻壓測。免費版 ngrok throttle 得好緊。要嘛 upgrade，要嘛將 handler 部去真實環境跑。
淨係跑 webhook、無其他 HTTP traffic 嘅場景。smee.io 更輕——唔使裝 binary，只要一個 client script。

常見問題

點解我用 UnifyPort webhook 要用 ngrok？: UnifyPort 將事件投遞去一個公網 HTTPS URL。跑喺 localhost:3000 嘅 handler 喺互聯網度連唔到，所以 ngrok 將兩邊駁起——一條命令就發佈一個 https://*.ngrok-free.app URL，將每個 request 轉去你嘅本地 port。
ngrok 會唔會搞壞 HMAC 簽章驗證？: 唔會。ngrok 免費版 tunnel 喺 upstream 解 TLS，但你 handler 收到嘅 body bytes 正正就係 UnifyPort 簽嗰啲 bytes。簽章驗證同 production 一模一樣：計 hex(HMAC-SHA256(secret, timestamp + "." + body))，再同 X-Device-Signature 對。
用真嘅 signing secret 嚟用 ngrok 安唔安全？: 本地開發用淨係開發用嘅 secret，係安全嘅——流量端到端加密，ngrok 個 inspector 又喺本地跑。但 staging 環境、demo、或者 production 級流量，就最好用付費 reserved ngrok domain，又或者轉去 Cloudflare Tunnel，會畀返個固定免費 hostname 你。