WhatsApp Webhook 重試、重複與次序:處理方法
Meta 會重試任何非 HTTP 200 回應的 WhatsApp Webhook,先即時重試,之後頻率逐漸減少,最長持續 7 天,期滿便會放棄。重試會發送至訂閱該 WhatsApp Business 帳戶的每個應用程式,因此重複訊息屬正常。請盡快回應 200,以訊息 ID,或 status ID 連同狀態值去重,並按事件本身的時間戳記排序。
easyCoexistence 透過 Coexistence 將你的 WhatsApp Business 應用程式號碼連接至 Meta 的 Cloud API,並在你的自動化看到訊息之前,先吸收 Meta 的重新送達,因此重試的訊息不會獲得第二次 AI 回覆。
Meta 在未收到 HTTP 200 後,會持續重試 Webhook 多久,之後才會放棄。
Meta 多數會把更新批次合併為一個 POST,但並不保證如此,因此每個請求都應獨立處理。
WhatsApp Webhook POST 可承載的最大負載。
easyCoexistence 會記住每個收到的訊息 ID 多久,使重新送達的訊息不會重複觸發自動化。
每次轉發至你的 Forward URL 時的嘗試次數,每次最多等待 10 秒以取得 2xx,整個過程約 33 小時。
Meta 何時會重試 WhatsApp Webhook?
每當送達至你的端點時收到非 HTTP 200 的狀態,或完全無法送達,Meta 便會重試。Meta 會即時重試,之後於 7 天內再重試數次,頻率逐漸減少;期滿仍未確認的內容則會被捨棄。重試會發送至該欄位所屬 WhatsApp Business 帳戶的每個應用程式,因此 Meta 警告可能產生重複通知。系統並無 API 可以取回過往的 Webhook,因此超過 7 天重試期的送達,便會永久遺失。
即使伺服器運作正常,為何仍會出現重複訊息?
因為送達在你的一方可能已成功,但在 Meta 看來仍屬失敗。處理程式若在回應前先完成工作,可能超過 Meta 的等待時限,Meta 便會重試你已處理過的內容。部署時伺服器於請求途中重新啟動、負載平衡器暫時回傳 502,或回傳 201 或 204 而非 200,都會被視為失敗。批次還會帶來另一種情況:一個 POST 可能包含大量更新,若大批次逾時,整批內容(包括你已處理的更新)都會被重新送回。
應以哪個鍵值去重?
應使用 Meta 自身的 ID,並按事件類型選擇,因為同一則訊息本來就會產生多個 Webhook。若狀態鍵缺少狀態值,`delivered` 與 `read` 會被誤當成 `sent` 的副本而遭捨棄;若通話鍵缺少事件,則只會保留通話的第一階段。請以唯一索引儲存這些鍵,使兩個處理同一次重試的工作程序無法同時成功:
Webhook 通常以什麼順序抵達?
不一定與事件實際發生的順序相同。Meta 的文件並無排序保證,重試的送達會晚於較新的送達抵達,而狀態亦可能跳過某一步:當訊息一抵達即被讀取,Meta 會直接送出 `read`,而不會先送 `delivered`。因此,應以各自的時間戳記欄位儲存事件,按等級而非抵達先後比較狀態,並讓較新的客戶訊息,優先於延遲抵達的較舊訊息。在 Coexistence 號碼上,開通時的一次性歷史紀錄匯入可能與即時訊息重疊,此時以訊息 ID 來對帳。
安全的處理程式應如何設計?
分為四個步驟:驗證、精準回應 200、去重,然後以佇列處理工作,使 Meta 的請求與你的回應之間不存在任何耗時步驟。此版本會以你自己的 Meta 應用程式密鑰檢查 X-Hub-Signature-256;對於透過 easyCoexistence 連接的號碼,Meta 會以 easyCoexistence 的應用程式密鑰簽署,因此直接送達的目的地,應改以網址路徑中的長密鑰驗證,或改用按號碼簽署的受管轉發。
// meta-webhook.mjs: node meta-webhook.mjs (no dependencies)
import crypto from "node:crypto";
import http from "node:http";
const APP_SECRET = process.env.META_APP_SECRET; // the secret of the Meta app that subscribed
const seen = new Set(); // keys already accepted: a unique index in a database in production
// One key per thing that happened, so a redelivery maps to the same keys.
function keysOf(field, value) {
const keys = [];
for (const m of value.messages ?? []) keys.push(`${field}:msg:${m.id}`);
for (const s of value.statuses ?? []) keys.push(`${field}:status:${s.id}:${s.status}`);
for (const e of value.message_echoes ?? []) keys.push(`${field}:echo:${e.id}`);
for (const c of value.calls ?? []) keys.push(`${field}:call:${c.id}:${c.event}`);
return keys;
}
http.createServer((req, res) => {
const chunks = [];
req.on("data", (c) => chunks.push(c));
req.on("end", () => {
const raw = Buffer.concat(chunks);
const got = Buffer.from(String(req.headers["x-hub-signature-256"] ?? ""));
const want = Buffer.from("sha256=" + crypto.createHmac("sha256", APP_SECRET).update(raw).digest("hex"));
if (req.method !== "POST" || got.length !== want.length || !crypto.timingSafeEqual(got, want)) {
res.writeHead(401).end();
return;
}
res.writeHead(200).end(); // exactly 200, before any work
const body = JSON.parse(raw.toString("utf8"));
for (const entry of body.entry ?? []) {
for (const change of entry.changes ?? []) {
for (const key of keysOf(change.field, change.value ?? {})) {
if (seen.has(key)) continue; // a retry of something already accepted
seen.add(key);
// queue { key, field: change.field, value: change.value } for a worker here
console.log("new", key);
}
}
}
});
}).listen(process.env.PORT ?? 3000);easyCoexistence 如何處理已連接號碼的重試?
在收到時,easyCoexistence 會檢查 Meta 的簽章,回應 200,並於回應之後才執行自動化,因此 Meta 不會因 AI 回覆花了幾秒而重試。每個收到的訊息 ID 會保留 7 天,即 Meta 重試期的長度;重新送達的訊息會被識別,不會再觸發第二次自動化回覆。
在轉發至你的 Forward URL 的一方,Meta 的每項變更都會成為一次傳送,其 X-EC-Delivery 中的 ID 在轉發重試時保持不變:最多 7 次嘗試,歷時約 33 小時,每次最多等待 10 秒以取得 2xx。若 Meta 本身重新送達某項變更,則會以新的傳送 ID 再次轉發,因此亦應在「value」欄位內依據 Meta 的 ID 去重。
常見錯誤
- 僅以 id 為準去重狀態。`sent`、`delivered` 與 `read` 共用同一個 wamid,因此鍵值也須包含狀態。
- 先處理後回應。處理緩慢會令 Meta 重試你已完成的工作;應先回傳 200,再以佇列處理。
- 回傳 201 或 204。Meta 的文件將非 200 的任何狀態視為送達失敗,並會重試。
- 只以 X-EC-Delivery 去重轉發。Meta 重新送達的變更會帶著新的傳送 ID 抵達;請將 Meta 的 ID 保留為第二個鍵值。
轉發至你伺服器的內容會經過簽署、排隊與重試,且全天候(24/7)監察每個號碼。每個已連接號碼每月 US$ 9 起,號碼越多越便宜,最低降至 US$ 0.75,首 3 天免費試用。
常見問題
我應保留已見過的 ID 多久?
至少 7 天,即 Meta 的重試期。Meta 在第六天重試的送達,必須仍能與其鍵值相符,否則會被當作新訊息處理。
若我的端點停機數日,客戶的訊息會怎樣?
Meta 最多重試 7 天,之後便會捨棄 Webhook。在 Coexistence 號碼上,對話仍保存在手機的 WhatsApp Business 應用程式內,因此商戶仍可從該處回覆。
我能重播錯過的 Webhook 嗎?
Meta 不提供此功能,並無 API 可取得歷史 Webhook 數據。Coexistence 號碼的一次性歷史紀錄匯入只會在開通時執行,同一連接無法再次請求。
Meta 會把同一更新發送至多於一個伺服器嗎?
會,Meta 會發送至訂閱該 WhatsApp Business 帳戶該欄位的每個應用程式。若設有目的地覆寫,則該號碼的訊息欄位會改送至覆寫網址,而非該應用程式的預設接收網址。
繼續閱讀
準備開始嗎?
幾分鐘內設定 WhatsApp Coexistence,而非幾個月。應用程式在手機上仍可繼續運作。
開始免費試用驗證日期