登录开始免费试用
Meta Tech Provider

WhatsApp Webhook 重试、重复与顺序:如何处理

Meta 会对返回非 HTTP 200 响应的 WhatsApp Webhook 立即重试,之后频率逐渐降低,最长持续 7 天,超过后便丢弃。重试会发送给订阅该账户的每个应用,因此重复消息很常见。请尽快返回 200,依据消息 ID,或依据状态 ID 加状态进行去重,并按事件自身的时间戳排序。

easyCoexistence 通过 Coexistence 将你的 WhatsApp Business 应用号码连接到 Meta 的 Cloud API,并在你的自动化看到之前吸收 Meta 的重新投递,因此重试的消息不会收到第二次 AI 回复。

7 days

Meta 在放弃某个未收到 HTTP 200 的 Webhook 之前,会持续重试多久。

1,000

Meta 会将大多数更新合并为一次 POST;Meta 不保证合并,因此每个请求都要单独处理。

3 MB

WhatsApp Webhook POST 能承载的最大负载。

7 days

easyCoexistence 会记住每个传入消息 ID 多久,以免重新投递的消息触发自动化两次。

7 attempts

每次转发至你的转发 URL 的尝试次数,每次最多等待 10 秒获取 2xx 响应,总时长约 33 小时。

Meta 何时会重试 WhatsApp Webhook?

只要投递到你的端点后收到的 HTTP 状态不是 200,或根本无法投递,Meta 就会重试。Meta 会立即重试,之后在接下来 7 天内再重试几次,频率逐渐降低,超过 7 天仍未确认的,便会丢弃。这些重试会发送给该字段所属 WhatsApp Business 账户下订阅的每个应用,因此 Meta 警告它们可能产生重复通知。没有可用于获取历史 Webhook 的 API,因此耗尽 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 的应用密钥签名,因此直接投递的目的地应改用 URL 路径中的长密钥进行认证,或改用按号码签名的托管转发。

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 的重试窗口长度,若遇到重新投递的消息,系统会识别它,不会再次触发自动化回复。

出站至你的转发 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 在第 6 天重试的投递仍须与其键匹配,否则会被当作新投递处理。

如果我的端点停机数天,客户的消息会怎样?

Meta 最多重试 7 天,之后丢弃 Webhook。对于 Coexistence 号码,对话仍保存在手机上的 WhatsApp Business 应用中,因此商家可以在那里回复。

我能重放错过的 Webhook 吗?

Meta 不提供此功能:没有获取历史 Webhook 数据的 API。Coexistence 号码的一次性历史导入仅在入驻时运行,同一连接无法再次请求。

Meta 会将同一更新发送到多个服务器吗?

会,它会发送给为该字段订阅 WhatsApp Business 账户的每个应用。若设有目标覆盖,号码的消息字段会发送到覆盖 URL,而不是该应用的默认 callback URL。

继续阅读

准备开始了吗?

几分钟即可设置 WhatsApp Coexistence,而不是几个月。应用会继续在手机上运行。

开始免费试用

验证时间