WhatsApp 訊息如何送達您的伺服器:直接或託管,以及驗證簽名
透過 easyCoexistence 連接的每個號碼,接收模式只有一種。直接送至您的系統(直接):Meta 把 Webhook 傳送到您的 HTTPS 端點,網址中的密鑰即是憑證,自動化關閉。透過 easyCoexistence(託管):Meta 把訊息傳送至 easyCoexistence,自動化可以回覆;選填的轉發 URL 會收到 Meta 的原始值及連接資料,並以 X-EC-Signature 簽名,供您驗證。
每次轉發投遞最多嘗試多次,間隔分別為 1 分鐘、5 分鐘、30 分鐘、2 小時、6 小時及 24 小時,合共約 33 小時。
每次轉發嘗試等待 2xx 回應的時限,逾時後才算失敗。
簽名中 t 時間戳的建議有效期上限;重試會重新簽名,因此正常投遞仍在有效期內。
Meta 對直接 Webhook 收到非 HTTP 200 回應時的重試時長,這可能導致訊息重複。
Meta 發送的最大 Webhook 負載大小,包括歷史資料分段。
託管號碼保留的執行紀錄包含訊息及回覆文字;訊息文字本身保留 30、90 或 365 天,由您選擇。
直接與託管有什麼分別?
指 Meta 把號碼的訊息 Webhook 傳送到哪裡。託管模式(介面上顯示「透過 easyCoexistence」)即 Meta 把訊息傳送至 easyCoexistence,由 easyCoexistence 驗證 Meta 的簽名、執行您的自動化、為「對話」保存聊天紀錄;若您設定了轉發 URL,則把每個 Meta 變更以只有您持有的密鑰簽名後轉發給您。直接模式(顯示為「直接送至您的系統」)指 easyCoexistence 把您的 HTTPS 端點設為該號碼 WhatsApp Business 帳戶上的 Webhook 覆寫,因此 Meta 直接向您傳送,訊息不會經過 easyCoexistence。
監控背後的營運 Webhook,例如 account_update 及品質變更,兩種模式下都由 easyCoexistence 處理,所以警示無論哪種模式都會持續運作。
| Managed: Through easyCoexistence | Direct: Straight to your system | |
|---|---|---|
| Meta delivers to | easyCoexistence, which verifies Meta's signature | Your HTTPS endpoint |
| Automations | Run on the number | Off |
| Your copy | Optional Forward URL, one Meta change per POST | Meta's envelope, unchanged |
| Proof it is genuine | X-EC-Signature, HMAC-SHA256 with the number's secret | A long random secret in the URL path |
| Failed deliveries | 7 attempts over about 33 hours | Meta retries for up to 7 days |
| History import | Not requested | Requested when saved within 24 hours of connecting |
| Kept by easyCoexistence | Message text 30, 90 or 365 days, run logs 30 days | Nothing |
如何在兩種模式之間切換號碼?
在號碼頁面的「收到的訊息去向」卡片會以兩個選項顯示模式:「透過 easyCoexistence」與「直接送至您的系統」。在「將收到的訊息路由至您自己的 Webhook」卡片中儲存 Webhook 目的地,或使用 set_webhook_destination,即可把號碼設為直接模式。選擇「透過 easyCoexistence」會立即在 Meta 移除該目的地,因此請把同一網址加入為轉發 URL,以繼續接收。號碼離開託管模式時,排隊中的轉發會被丟棄;沒有 Webhook 網址連接的號碼則以託管模式開始。
透過您的 AI,set_inbound_mode 可以一次切換模式並設定轉發,並且只會返回一次轉發密鑰:
// set_inbound_mode arguments
{
"connection_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
"mode": "managed",
"forward_url": "https://agent.example.com/ec/forward"
}
// result: forward_secret is shown once
{
"connection_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
"mode": "managed",
"forward_url": "https://agent.example.com/ec/forward",
"forward_secret": "whsec_Qm9vbXRoZXNlY3JldHNhcmVmYWtlMTIz",
"secret_note": "Shown once. Verify X-EC-Signature: t=<unix>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with it; the body's value is Meta's original payload.",
"direct_destination": null
}轉發的 POST 包含什麼?
每個請求只包含一項 Meta 變更,並以包裝形式傳送,而非 Meta 的 object、entry 及 changes 結構。id 是投遞 ID,同時在 X-EC-Delivery 中重複,且在重試時保持不變。event 是 Meta 的欄位名稱,即 messages、smb_message_echoes、history 或 smb_app_state_sync,同時在 X-EC-Event 中重複。received_at 是 easyCoexistence 從 Meta 取得該變更的時間,connection 標示號碼,value 則是 Meta 原樣傳送的內容,因此為 Meta 負載編寫的解析程式可直接用於此內容。投遞狀態會放在 messages 事件中,位於 value.statuses 之下。
POST /ec/forward HTTP/1.1
Content-Type: application/json
User-Agent: easyCoexistence-forward/1
X-EC-Event: messages
X-EC-Delivery: 8c1d7e52-0f4b-4a3e-9d61-2b7f5a9e0c13
X-EC-Signature: t=1794405732,v1=<64 hex characters>
{
"id": "8c1d7e52-0f4b-4a3e-9d61-2b7f5a9e0c13",
"event": "messages",
"received_at": "2026-11-11T14:02:11.482Z",
"connection": {
"id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
"phone": "+1 631-555-0142",
"phone_number_id": "106540352242922",
"waba_id": "102290129340398",
"external_ref": null
},
"value": {
"messaging_product": "whatsapp",
"metadata": { "display_phone_number": "16315550142", "phone_number_id": "106540352242922" },
"contacts": [{ "profile": { "name": "Ana Souza" }, "wa_id": "5511987654321", "user_id": "BR.13491208655302741918" }],
"messages": [{
"from": "5511987654321",
"from_user_id": "BR.13491208655302741918",
"id": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFjNFQjBDNzE4RjQ2QjI5RDkxQTNFAA==",
"timestamp": "1794405731",
"type": "text",
"text": { "body": "Do you deliver on Sundays?" }
}]
}
}如何在 Node.js 中驗證 X-EC-Signature?
讀取標頭,格式為 t=<unix 秒數>,v1=<64 個十六進位字元>。若 t 與您的時鐘相差超過 5 分鐘,即拒絕。以完整轉發密鑰的 UTF-8 文字作為金鑰,對 t、一個點號及原始內容計算 HMAC-SHA256,並以常數時間與 v1 比較。驗證通過後才解析 JSON。請在 10 秒內回應 2xx,之後再處理工作,並記下已接受的投遞 ID,以免重試時重複處理。
// forward-receiver.mjs: node forward-receiver.mjs (no dependencies)
import crypto from "node:crypto";
import http from "node:http";
const SECRET = process.env.EC_FORWARD_SECRET; // the whole whsec_... string is the HMAC key
const taken = new Set(); // delivery ids already accepted: use a database in production
export function verifyEcSignature(raw, header, secret = SECRET, maxAgeSec = 300) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(String(header ?? "").trim());
if (!m || !secret) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - Number(m[1])) > maxAgeSec) return false;
const mac = crypto.createHmac("sha256", secret).update(`${m[1]}.`).update(raw).digest();
return crypto.timingSafeEqual(mac, Buffer.from(m[2], "hex"));
}
http.createServer((req, res) => {
const chunks = [];
req.on("data", (c) => chunks.push(c));
req.on("end", () => {
const raw = Buffer.concat(chunks);
if (req.method !== "POST" || !verifyEcSignature(raw, req.headers["x-ec-signature"])) {
res.writeHead(401).end();
return;
}
res.writeHead(200).end(); // a 2xx within 10 s, before any work
const d = JSON.parse(raw.toString("utf8"));
if (taken.has(d.id)) return; // a retry of a delivery already accepted
taken.add(d.id);
// d.event is the Meta field (messages, smb_message_echoes, history, smb_app_state_sync)
// d.value is Meta's change value, unchanged; queue it for your worker here.
console.log(d.event, d.connection.phone_number_id, Object.keys(d.value));
});
}).listen(process.env.PORT ?? 3000);如何在 Python 中驗證?
使用標準函式庫,做同樣的四項檢查:以嚴格的格式比對檢查標頭、檢查 t 的時間、以 hmac.new 對 t、一個點號及原始位元組計算,然後使用 hmac.compare_digest 比較。在 FastAPI 中,原始內容由 await request.body() 取得,BackgroundTasks 會在 200 送出後執行工作。在 Flask 中,請使用 request.get_data();切勿以 json.dumps 重建內容,因為 Python 預設分隔符會加入空格,簽名便會不符。
# forward_receiver.py: pip install fastapi uvicorn, then uvicorn forward_receiver:app
import hashlib, hmac, json, os, re, time
from fastapi import BackgroundTasks, FastAPI, Request, Response
app = FastAPI()
SECRET = os.environ["EC_FORWARD_SECRET"].encode() # the whole whsec_... string, as bytes
SIGNATURE = re.compile(r"t=([0-9]+),v1=([0-9a-f]{64})")
taken = set() # delivery ids already accepted: use a database in production
def verify_ec_signature(raw: bytes, header: str, max_age: int = 300) -> bool:
m = SIGNATURE.fullmatch(header.strip())
if not m or abs(int(time.time()) - int(m[1])) > max_age:
return False
mac = hmac.new(SECRET, m[1].encode() + b"." + raw, hashlib.sha256).hexdigest()
return hmac.compare_digest(mac, m[2])
def process(delivery: dict) -> None:
if delivery["id"] in taken: # a retry of a delivery already accepted
return
taken.add(delivery["id"])
print(delivery["event"], delivery["connection"]["phone_number_id"], list(delivery["value"]))
@app.post("/ec/forward")
async def forward(request: Request, tasks: BackgroundTasks):
raw = await request.body()
if not verify_ec_signature(raw, request.headers.get("x-ec-signature", "")):
return Response(status_code=401)
tasks.add_task(process, json.loads(raw)) # runs after the 200 goes out
return Response(status_code=200)失敗的投遞如何重試?
只要您的端點在 10 秒內回應任何 2xx,轉發即視為已投遞。其他情況,包括逾時、4xx、5xx,或不會被跟隨的重新導向,都會安排下一次嘗試,分別於約 1 分鐘、5 分鐘、30 分鐘、2 小時、6 小時及 24 小時後進行;第七次嘗試後,該投遞即被放棄。每次嘗試都會以新的 t 重新簽名,而且網址必須是公開的 HTTPS,儲存時及每次發送前都會檢查。投遞按由舊至新的次序發出,但重試的投遞可能晚於較新的投遞抵達,因此請依 Meta 的時間戳排序。
在直接目的地中,由 Meta 負責重試:除 HTTP 200 以外的任何回應,都會以逐漸降低的頻率重試最多 7 天,而這些重試可能令訊息重複。在兩種模式中,都應以 Meta 的訊息 ID 去重,因為 Meta 重新投遞的變更,會以新的投遞 ID 再次轉發。
直接端點如何確定 POST 是真實的?
不能只靠 X-Hub-Signature-256。Meta 會以擁有該訂閱的應用程式之應用程式密鑰簽名;對於在此連接的號碼,該應用程式是 easyCoexistence 的,並不會共用,因此若以您自己的 Meta 應用程式密鑰驗證該標頭,會拒絕真正的投遞。驗證權杖只會在 Meta 的 GET 握手期間證明端點一次。以下方法可行:
- 在 Webhook 網址路徑中加入 32 個或以上的隨機字元,並拒絕不含此字串的請求;如要輪換,儲存新網址即可。
- 使用通用接收器,例如 n8n Webhook 節點,而非預期您自己 Meta 應用程式的 WhatsApp 觸發器。
- 以號碼的權杖向 Meta 按 ID 下載媒體,偽造的 ID 會直接失敗。
- 在自行架設的伺服器上,可選擇只允許 Meta 的網絡,即 AS32934 所公布的路由。
- 或改用託管模式並設定轉發 URL,由 X-EC-Signature 證明每個 POST。
常見錯誤
- 把為 Meta 信封編寫的程式碼直接指向轉發 URL 而不作修改。轉發只包含一項變更:請讀取 event 及 value,而非 object、entry 及 changes。
- 等待 X-EC-Event 為 statuses。投遞狀態位於 messages 事件中的 value.statuses,而在應用程式中輸入的回覆會以 smb_message_echoes 形式送達。
- 先處理工作,後回應。轉發會等候 10 秒,之後同一投遞會以新的 t 再次送來;請先回應 2xx,再從佇列處理。
- 切換至託管模式後,仍以為舊網址會接收。直接目的地會在該時刻被移除;請在同一個 set_inbound_mode 呼叫中傳入 forward_url。
easyCoexistence 透過 Coexistence 把 WhatsApp Business 應用程式號碼連接至 Meta 的 Cloud API,並讓您逐個號碼選擇訊息的去向:由 Meta 直接送至您的伺服器,或經 easyCoexistence 送達,讓自動化能夠回覆,並把已簽名的副本送至轉發 URL。兩種模式下監控及警示都能運作。每個號碼每月由 US$ 9 起,號碼越多越便宜,最低降至 US$ 0.75,並提供首 3 天免費試用。
常見問題
我的伺服器能看到自動化回覆了什麼嗎?
看不到文字。Meta 會以 statuses(已傳送、已投遞、已讀)的形式,在 messages 事件中附同訊息 ID 回報 API 發送的情況;回覆文字本身則保存在自動化的執行紀錄中,於「執行紀錄」分頁保留 30 天,並在「對話」中按您所選的期限保留。
如何輪換轉發密鑰?
在號碼頁面按「產生新密鑰」,或以 rotate_secret 設為 true 呼叫 set_inbound_mode。新密鑰只會顯示一次,並從此刻起為所有內容簽名,包括舊投遞的重試,因此請即時更新您的伺服器。
轉發 URL 需要 Meta 的 GET 握手嗎?
不需要。只有直接目的地會由 Meta 呼叫,並須回傳 hub.challenge。轉發 URL 由 easyCoexistence 呼叫,只接收已簽名的 POST。
同一號碼能否同時設有直接目的地及轉發 URL?
不能。轉發 URL 只在號碼為託管模式時有效,而儲存直接目的地會令號碼改為直接模式。轉發 URL 及其密鑰會被保留,因此切換回託管模式後,轉發會恢復。
繼續閱讀
準備開始嗎?
幾分鐘內設定 WhatsApp Coexistence,而非幾個月。應用程式在手機上仍可繼續運作。
開始免費試用驗證日期