Telegram Webhook secret_token 與 HMAC：接收端該驗證什麼
Telegram Bot API 的 secret_token 不是 HMAC 簽章。透過 setWebhook 設定後，Telegram 會把同一個值放在 X-Telegram-Bot-Api-Secret-Token 標頭中，接收端將它與本地設定的權杖比對。UnifyPort 使用另一種契約：啟用簽章後，必須以時間戳記和原始請求本文計算 HMAC-SHA256，再驗證 X-Device-Signature。這兩種檢查不能互換。
必須先釐清的差異
- Telegram 標頭直接攜帶共用憑證，不是由 JSON 本文計算的摘要。
- UnifyPort 以端點的
signing_secret，將原始本文與X-Device-Timestamp納入簽章。 - 兩種接收端都需要 HTTPS、妥善保存密鑰，以及冪等處理。
- 驗證方式應由可信任的路由設定決定，不能依尚未驗證的
provider欄位或任意出現的標頭選擇。
本文討論的是請求驗證，而非帳號身分選擇。若還沒決定使用機器人或既有通訊帳號，請先看 Telegram Bot API webhook 與統一入站 webhook 比較。
Telegram secret_token 究竟驗證什麼
Telegram 官方 Bot API 文件將 secret_token 列為 setWebhook 的選用參數：長度為 1–256 個字元，只允許 A-Z、a-z、0-9、_ 與 -。設定後，每次 webhook 請求都會透過 X-Telegram-Bot-Api-Secret-Token 傳送該值。
若接收端要求這項保護，缺少或不符的標頭就不能進入受信任的處理佇列。完全相符代表請求方持有設定的值，但不代表該值與本文之間存在獨立的密碼學關聯。
這在代理或轉送服務處尤其重要：能讀到權杖的元件，也能使用相同權杖提交不同本文。HTTPS 保護傳輸連線，但靜態標頭本身無法偵測 TLS 終止後的本文變更。這是信任邊界的差異，不是要求你放棄官方 Bot API。
建議使用專屬的 webhook 憑證，不要重複使用 bot token，也不要將密鑰貼到公開的請求擷取服務。存取紀錄、追蹤資料與客服截圖都應遮蔽敏感值。
靜態權杖與本文簽章比較
HMAC 是使用共用密鑰的訊息認證機制。UnifyPort 文件要求接收端重新計算指定輸入的摘要，而非直接比對簽章標頭與密鑰。
| 問題 | Telegram Bot API webhook | 已簽章的 UnifyPort webhook |
|---|---|---|
| 設定項目 | setWebhook.secret_token | 端點的 signing_secret |
| 驗證標頭 | X-Telegram-Bot-Api-Secret-Token | X-Device-Signature |
| 收到的值 | 設定的權杖本身 | 十六進位 HMAC-SHA256 摘要 |
| 包含本文嗎？ | 否 | 是，原始位元組 |
| 包含時間戳記嗎？ | 否 | 是，X-Device-Timestamp |
| 接收端操作 | 比對標頭與權杖 | 重算並比對摘要 |
| 保證只處理一次嗎？ | 否 | 否 |
UnifyPort 的簽章輸入必須是：
<X-Device-Timestamp>.<raw request body>時間戳記採 RFC 3339 UTC 格式，中間是字面上的句點。重新格式化 JSON、變更空白，或先解析再序列化，都可能改變已簽章的位元組。signing_secret 是 HMAC 密鑰，不是簽章標頭應直接等於的值。
若 signing_secret 為空，UnifyPort 會停用簽章並省略 X-Device-Signature。要求簽章的接收端應拒絕這種請求，不能悄悄改用其他驗證方式。
讓兩種流量使用各自的入口
建議為原生 Telegram 更新與 UnifyPort 事件建立不同的應用程式路由。這是應用程式設計建議，不是新增的平台 API 端點。
- 綁定來源與憑證。 在部署設定中指定各路由採用哪一種驗證契約。
- 先驗證再分派。 Telegram 檢查權杖標頭；已簽章的 UnifyPort 請求檢查原始本文 HMAC 與時間戳記新鮮度。
- 依正確結構驗證資料。 不要將原生 Telegram
Update交給期待 UnifyPortmessage.received的處理器。 - 持久保存已接受的工作。 將認證、冪等與業務授權分開處理。
- 記錄失敗類型，不記錄密鑰。 排查時只需知道哪一項檢查失敗。
不要讓共用中介軟體採用「任一標頭通過即可」的規則。否則，較弱或意外啟用的分支就會成為另一條通過驗證的途徑。Telegram 權杖尤其不能取代 UnifyPort 路由所要求的 HMAC。
想實作第二套契約，可參考 HMAC 重播防護與重試處理。訊息 JSON 裡的時間欄位，不能取代受到投遞簽章保護的時間戳記。
上線前的驗收測試
以下是建議測試，並非已執行的結果。請在隔離環境使用自己控制的憑證。
| 測試 | 預期行為 |
|---|---|
| Telegram 標頭缺少或不符 | 在受信任處理前拒絕 |
| Telegram 權杖正確，但本文被改變 | 單靠權杖無法察覺；仍須驗證資料結構並維持可信傳輸邊界 |
| UnifyPort 本文在簽章後被改變 | 摘要不符，拒絕 |
| UnifyPort 簽章有效，但時間超出設定窗口 | 依新鮮度政策拒絕 |
| 將 Telegram 權杖送到 UnifyPort 路由 | 拒絕，不改變驗證方式 |
| 同一真實的一般事件再次投遞 | 冪等接受，不重複執行业務操作 |
新鮮度窗口應依時鐘準確度與投遞條件設定，不要直接複製其他平台的數值。請求驗證成功，也不代表訊息中的每個指令都具有業務執行權限。
UnifyPort 的適用範圍與限制
UnifyPort 非官方介面提供已連接通訊帳號的標準化事件。HMAC 保護的是 UnifyPort 到你的接收端這段交接，不是 Telegram 原生簽章，也不是 Telegram 使用者端到端作者身分的證明。
若產品本來就是 Telegram 機器人，依 Telegram 文件保護該入口即可，不必只為改用另一種驗證方式而遷移平台。若使用 UnifyPort 建立帳號級或跨管道佇列，就應遵循其獨立契約，並在建立 webhook 端點時啟用簽章。
常見問題
需要用 Telegram secret_token 計算 HMAC 嗎？
驗證官方 Bot API 的密鑰標頭時不需要。直接比對標頭與設定的權杖，不要自行替這個標頭設計本文簽章演算法。
可以直接比對 X-Device-Signature 與 signing_secret 嗎？
不行。先對文件指定的「時間戳記加原始本文」計算 HMAC-SHA256，再比對收到的十六進位簽章。
這兩種方式能防止重複處理嗎？
不能。認證與去重是不同的工作。持久保存已接受的任務，並讓下游操作保持冪等；HMAC 本身不保證只處理一次。
下一步與來源
以 webhook 投遞與簽章驗證文件作為 UnifyPort 接收端的實作契約。
來源核對日期：2026-09-17。
讓訊息接入變成一條穩定的產品管線。
先用統一 API 跑通傳送，再用標準事件把所有入站訊息接回業務系統。