登入開始免費試用
Meta Tech Provider

WhatsApp Webhook 重試、重複與次序:處理方法

Meta 會重試任何非 HTTP 200 回應的 WhatsApp Webhook,先即時重試,之後頻率逐漸減少,最長持續 7 天,期滿便會放棄。重試會發送至訂閱該 WhatsApp Business 帳戶的每個應用程式,因此重複訊息屬正常。請盡快回應 200,以訊息 ID,或 status ID 連同狀態值去重,並按事件本身的時間戳記排序。

easyCoexistence 透過 Coexistence 將你的 WhatsApp Business 應用程式號碼連接至 Meta 的 Cloud API,並在你的自動化看到訊息之前,先吸收 Meta 的重新送達,因此重試的訊息不會獲得第二次 AI 回覆。

7 days

Meta 在未收到 HTTP 200 後,會持續重試 Webhook 多久,之後才會放棄。

1,000

Meta 多數會把更新批次合併為一個 POST,但並不保證如此,因此每個請求都應獨立處理。

3 MB

WhatsApp Webhook POST 可承載的最大負載。

7 days

easyCoexistence 會記住每個收到的訊息 ID 多久,使重新送達的訊息不會重複觸發自動化。

7 attempts

每次轉發至你的 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` 的副本而遭捨棄;若通話鍵缺少事件,則只會保留通話的第一階段。請以唯一索引儲存這些鍵,使兩個處理同一次重試的工作程序無法同時成功:

messages[].idIncoming messages: the wamid.
statuses[].id + statusOne message has sent, delivered, read; each is its own event.
message_echoes[].idReplies the owner typed in the WhatsApp Business app.
calls[].id + eventA call's connect, statuses and terminate share the wacid.
user id + value + timestampuser_preferences: a customer can stop and resume more than once.

Webhook 通常以什麼順序抵達?

不一定與事件實際發生的順序相同。Meta 的文件並無排序保證,重試的送達會晚於較新的送達抵達,而狀態亦可能跳過某一步:當訊息一抵達即被讀取,Meta 會直接送出 `read`,而不會先送 `delivered`。因此,應以各自的時間戳記欄位儲存事件,按等級而非抵達先後比較狀態,並讓較新的客戶訊息,優先於延遲抵達的較舊訊息。在 Coexistence 號碼上,開通時的一次性歷史紀錄匯入可能與即時訊息重疊,此時以訊息 ID 來對帳。

安全的處理程式應如何設計?

分為四個步驟:驗證、精準回應 200、去重,然後以佇列處理工作,使 Meta 的請求與你的回應之間不存在任何耗時步驟。此版本會以你自己的 Meta 應用程式密鑰檢查 X-Hub-Signature-256;對於透過 easyCoexistence 連接的號碼,Meta 會以 easyCoexistence 的應用程式密鑰簽署,因此直接送達的目的地,應改以網址路徑中的長密鑰驗證,或改用按號碼簽署的受管轉發。

meta-webhook.mjs: 200 first, then deduplicate (Node.js, no dependencies)
// 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 保留為第二個鍵值。
使用 EasyCoexistence 完成這項設定

轉發至你伺服器的內容會經過簽署、排隊與重試,且全天候(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,而非幾個月。應用程式在手機上仍可繼續運作。

開始免費試用

驗證日期