保護你的 WhatsApp 自動化:金鑰、Webhook 與簽章
在四個環節保護 WhatsApp 自動化:AI 金鑰以加密方式儲存,且只用於 AI 回覆;自動化所呼叫的 webhook 應在信任請求前檢查 HMAC 簽章;收到訊息的轉發以可輪換的簽署密鑰簽署;以及有權限的人員與助理,只獲授予其所需的存取權。
easyCoexistence 將你的 AI 金鑰加密儲存,且之後不再顯示;每個「Call my webhook」請求與每則轉發的訊息,都以只有你持有的密鑰透過 X-EC-Signature 簽署,並拒絕非公開 HTTPS 的 webhook 位址。
靜態加密儲存已保存的 AI 金鑰、簽署密鑰,以及號碼的 Meta 存取權杖。
已保存的 AI 金鑰之後只會以「ending in」加其最後四個字元顯示。
每組簽署密鑰都具隨機性:whsec_ 加上 24 個隨機位元組,每個自動化與每個轉發號碼各一組。
Webhook 與轉發 URL 必須為公開的 HTTPS;私有及內部位址會在儲存時及每次發送前被拒絕。
建議限制簽章中 t 值的時效,以拒絕重播的請求。
WhatsApp 自動化設定中需要保護什麼?
共有五項憑證,各自有其存放位置,洩露時也各有補救方法。其中兩項屬於自動化本身,即 AI 金鑰與「Call my webhook」的簽署密鑰;轉發的簽署密鑰屬於號碼;存取權杖與你的助理登入則屬於帳戶。分清楚哪項屬於哪裡,出現問題時便知道該輪換哪一項。
AI 金鑰如何儲存與使用?
只能透過控制台操作:在自動化頁面按下「AI keys」按鈕,然後按「Test and save」。金鑰會先向供應商的一個免費端點檢查,不會消耗任何 AI 用量;供應商拒絕的金鑰會被丟棄,不會被儲存。有效的金鑰以 AES-256-GCM 加密儲存,只在你的 AI 步驟與代理需要呼叫該供應商時,以及在 OpenAI 或 OpenRouter 金鑰上轉寫語音訊息時才會解密,之後僅以「ending in 1234」的形式顯示。沒有任何 MCP 工具會接受或回傳金鑰,因此金鑰不會經過你與助理的對話。
每個帳戶每個供應商只能保存一把金鑰,儲存新金鑰會取代舊的。請在供應商處為自動化建立專用金鑰,並在供應商提供的情況下設定消費上限,這樣即使撤銷該金鑰,也不會影響你的其他應用程式。若供應商拒絕該金鑰,使用它的自動化會顯示「Paused」,你會收到一封電郵;儲存一把有效的金鑰後,它們會自行恢復運作。
如何驗證「Call my webhook」請求確實是真實的?
先檢查簽章,再處理其他任何內容。每個請求都帶有 X-EC-Signature:t=<unix seconds>,v1=<hex HMAC-SHA256 of 「<t>.<raw body>」>,以該自動化的簽署密鑰(於儲存後從編輯器的步驟中複製)為密鑰。請對原始位元組重新計算 HMAC,以恆定時間比較,並拒絕與你的時鐘相差超過 5 分鐘的 t。內容本身還有兩點值得採取行動:當請求來自「Try it」時,dry_run 為 true,因此應跳過任何不可逆的操作,例如建立訂單;run_id 則對每次執行都是唯一的,請記下已處理的 run_id,並拒絕重播的請求。請在 20 秒內回應;{"reply": "..."} 會原封不動地傳送給客戶,因此切勿在未經檢查的情況下傳遞客戶的文字。
POST /hooks/whatsapp HTTP/1.1
Content-Type: application/json
User-Agent: easyCoexistence-automations/1
X-EC-Event: automation.step
X-EC-Signature: t=1794405732,v1=<64 hex characters>
{
"event": "automation.step",
"dry_run": false,
"automation": { "id": "a7d0c3e2-5b1f-4c8e-9a6d-2f4e8b1c7d90", "name": "Order status" },
"run_id": "e41b9f07-3c2a-4d6e-8f15-7a9c0b2d4e68",
"channel": { "type": "whatsapp", "connection_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "phone": "+1 631-555-0142", "phone_number_id": "106540352242922" },
"connection": { "id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "phone": "+1 631-555-0142", "phone_number_id": "106540352242922" },
"contact": { "id": "5511987654321", "wa_id": "5511987654321", "name": "Ana Souza" },
"message": { "id": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFjNFQjBDNzE4RjQ2QjI5RDkxQTNFAA==", "type": "text", "text": "Where is my order #1042?", "at": "2026-11-11T14:02:11.000Z" },
"history": [
{ "direction": "in", "text": "Hi!", "at": "2026-11-11T14:01:40.120Z" },
{ "direction": "in", "text": "Where is my order #1042?", "at": "2026-11-11T14:02:11.310Z" }
]
}
// Your answer, within 20 seconds (or {} to send nothing):
{ "reply": "Your order #1042 left the shop at 2:20 p.m." }轉發簽署密鑰如何運作?如何輪換?
設為「Through easyCoexistence」的號碼可以將收到的訊息轉發至你自己的系統。你第一次儲存轉發 URL 時,會產生一組簽署密鑰,並只顯示一次,標示為「Your signing secret, shown once. Copy it now:」;每個轉發的 POST 都以相同的 X-EC-Signature 方案簽署。在號碼頁面按下「New secret」,或以 rotate_secret 設為 true 呼叫 set_inbound_mode,即可產生替代密鑰,同樣只顯示一次,之後的所有簽署(包括較早傳送內容的重試)都會使用新密鑰。你也可以自行輸入一組至少 24 個字元的密鑰,它會被儲存且不再顯示。停止轉發會刪除該密鑰,因此日後再儲存 URL 時會從新的密鑰開始。
以下情況後應輪換密鑰:有擁有存取權的團隊成員離職後;密鑰外洩到儲存庫、工單或日誌中後;以及更換主機時。「Call my webhook」的簽署密鑰屬於該自動化,只有帳戶擁有者看得到。若編輯器在「Your system calls a URL」觸發條件下顯示「New secret」,該按鈕會替換密鑰,舊密鑰立即失效;若自動化沒有該按鈕,請重新建立該自動化,讓你的接收端改用新密鑰,然後刪除舊的自動化。
自動化可以呼叫哪些位址?
只限公開的 HTTPS 位址。若「Call my webhook」URL 或轉發 URL 以 http:// 開頭、指向 localhost、私有網絡範圍、.internal 或 .local 名稱,或雲端中繼資料位址,儲存時便會被拒絕;每次請求前在 DNS 解析後也會再次檢查,因此公開名稱日後不能被指向私有網絡。重新導向不會被跟隨:301 或 302 會令該步驟失敗,因此請儲存最終位址。
請勿把密鑰放在 URL 本身之中。list_automations 會把每個自動化的步驟(包括 Webhook URL)回傳給連接你帳戶的任何助理,因此查詢字串中的權杖在那裡是可以被讀取的。請改由簽章負責證明身分。
如何將存取權限降至最低?
為每個人與每個工具只授予其工作所需的權限,並移除不再使用的權限。連接器一側的登入、確認與封鎖工具,已在關於如何安全地把 WhatsApp 連接至 AI 的頁面中說明;就自動化一側而言,以下習慣最為重要:
- 只在私人對話中要求
get_api_credentials:號碼的存取權杖會留在該對話記錄中。 - 優先使用「Call my webhook」或轉發 URL,而非把權杖交給第三方工具。
- 刪除已停用的自動化;這同時也會令其簽署密鑰失效。
- 請記住,執行日誌會保存客戶的訊息與回覆達 30 天,「對話」則會在你的保留期限(30、90 或 365 天)內保留對話,兩者皆可在控制台及連接你的助理中讀取。
- 若號碼設定為「Straight to your system」,請在回呼 URL 路徑中加入一段長而隨機的密鑰,因為 Meta 的簽章在該情況下無法被驗證。
常見錯誤
- 以經框架重新序列化的 JSON 驗證簽章。許多解析器會改變空格、跳脫字元或鍵的次序;只要你的技術棧提供原始請求位元組,就應對原始位元組計算 HMAC。
- 在測試呼叫中執行副作用。「Try it」會以 dry_run 設為 true 呼叫你的 webhook;此時建立的訂單、退款或 CRM 寫入都是真實的。
- 為省時而把 AI 金鑰貼到與助理的對話中。沒有任何工具接受它,而且它會留在對話記錄中;請在控制台中使用 AI 金鑰。
- 用 Call my webhook 的簽署密鑰來檢查轉發,或反過來做。兩者是獨立的密鑰:轉發每個號碼一組,webhook 呼叫每個自動化一組。
你的號碼透過 Coexistence 繼續使用 Meta 官方的 Cloud API,並全天候 24/7 監察。每個號碼每月 US$ 9 起,號碼越多越便宜,最低降至 US$ 0.75,首 3 天免費。
常見問題
easyCoexistence 的員工或支援人員能看到我的 AI 金鑰嗎?
金鑰在你儲存後永不顯示,無論在控制台、MCP 結果中,或支援助理讀取的資料中都不會出現。只有系統會在為 AI 回覆而呼叫你的供應商時解密。
誰可以讀取我的自動化執行日誌?
任何登入你 easyCoexistence 帳戶的人(包括你邀請的人),都可在「Runs」標籤中查看;連接該帳戶的任何助理也可透過 list_automation_runs 與 get_automation_run 查看。日誌包含客戶的訊息與回覆,並會在 30 天後刪除。
如何安全地移除 AI 金鑰?
先關閉使用該金鑰的自動化(「Switch Off」)以及任何以該金鑰運行的代理,然後在「AI keys」下選擇「Remove」,並在供應商處撤銷該金鑰。若自動化仍在使用時移除金鑰,它們會在下次 AI 回覆時暫停,並向你發送一封電郵。
「Try it」會把客戶資料送到我的 webhook 嗎?
只會送出你輸入的範例文字,dry_run 設為 true,歷史紀錄為空。真正的執行則會送出收到的訊息及該對話最近的訊息(最多 10 則),因此請把你的端點視為處理客戶資料的系統。
繼續閱讀
準備開始嗎?
幾分鐘內設定 WhatsApp Coexistence,而非幾個月。應用程式在手機上仍可繼續運作。
開始免費試用驗證日期