登入開始免費試用
Meta Tech Provider

WhatsApp 訊息如何送達您的伺服器:直接或託管,以及驗證簽名

透過 easyCoexistence 連接的每個號碼,接收模式只有一種。直接送至您的系統(直接):Meta 把 Webhook 傳送到您的 HTTPS 端點,網址中的密鑰即是憑證,自動化關閉。透過 easyCoexistence(託管):Meta 把訊息傳送至 easyCoexistence,自動化可以回覆;選填的轉發 URL 會收到 Meta 的原始值及連接資料,並以 X-EC-Signature 簽名,供您驗證。

7 attempts

每次轉發投遞最多嘗試多次,間隔分別為 1 分鐘、5 分鐘、30 分鐘、2 小時、6 小時及 24 小時,合共約 33 小時。

10 s

每次轉發嘗試等待 2xx 回應的時限,逾時後才算失敗。

5 min

簽名中 t 時間戳的建議有效期上限;重試會重新簽名,因此正常投遞仍在有效期內。

7 days

Meta 對直接 Webhook 收到非 HTTP 200 回應時的重試時長,這可能導致訊息重複。

3 MB

Meta 發送的最大 Webhook 負載大小,包括歷史資料分段。

30 days

託管號碼保留的執行紀錄包含訊息及回覆文字;訊息文字本身保留 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 easyCoexistenceDirect: Straight to your system
Meta delivers toeasyCoexistence, which verifies Meta's signatureYour HTTPS endpoint
AutomationsRun on the numberOff
Your copyOptional Forward URL, one Meta change per POSTMeta's envelope, unchanged
Proof it is genuineX-EC-Signature, HMAC-SHA256 with the number's secretA long random secret in the URL path
Failed deliveries7 attempts over about 33 hoursMeta retries for up to 7 days
History importNot requestedRequested when saved within 24 hours of connecting
Kept by easyCoexistenceMessage text 30, 90 or 365 days, run logs 30 daysNothing

如何在兩種模式之間切換號碼?

在號碼頁面的「收到的訊息去向」卡片會以兩個選項顯示模式:「透過 easyCoexistence」與「直接送至您的系統」。在「將收到的訊息路由至您自己的 Webhook」卡片中儲存 Webhook 目的地,或使用 set_webhook_destination,即可把號碼設為直接模式。選擇「透過 easyCoexistence」會立即在 Meta 移除該目的地,因此請把同一網址加入為轉發 URL,以繼續接收。號碼離開託管模式時,排隊中的轉發會被丟棄;沒有 Webhook 網址連接的號碼則以託管模式開始。

透過您的 AI,set_inbound_mode 可以一次切換模式並設定轉發,並且只會返回一次轉發密鑰:

set_inbound_mode: arguments and result
// 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 之下。

A forwarded messages event: headers and body
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.js, no dependencies)
// 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 (FastAPI)
# 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 完成這項設定

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,而非幾個月。應用程式在手機上仍可繼續運作。

開始免費試用

驗證日期