WhatsApp Webhook 重试、重复与顺序:如何处理
Meta 会对返回非 HTTP 200 响应的 WhatsApp Webhook 立即重试,之后频率逐渐降低,最长持续 7 天,超过后便丢弃。重试会发送给订阅该账户的每个应用,因此重复消息很常见。请尽快返回 200,依据消息 ID,或依据状态 ID 加状态进行去重,并按事件自身的时间戳排序。
easyCoexistence 通过 Coexistence 将你的 WhatsApp Business 应用号码连接到 Meta 的 Cloud API,并在你的自动化看到之前吸收 Meta 的重新投递,因此重试的消息不会收到第二次 AI 回复。
Meta 在放弃某个未收到 HTTP 200 的 Webhook 之前,会持续重试多久。
Meta 会将大多数更新合并为一次 POST;Meta 不保证合并,因此每个请求都要单独处理。
WhatsApp Webhook POST 能承载的最大负载。
easyCoexistence 会记住每个传入消息 ID 多久,以免重新投递的消息触发自动化两次。
每次转发至你的转发 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 的副本而遭丢弃;若通话键不含事件,则只会保留通话的第一个阶段。请将这些键存入带唯一索引的存储中,使两个处理同一次重试的工作进程不会同时成功:
Webhook 按什么顺序到达?
不一定与事件实际发生的顺序相同。Meta 的文档不承诺顺序,被重试的投递会晚于较新的投递到达,而且状态可能跳过某一步:消息一到达即被阅读时,Meta 只发送 read,不发送 delivered。因此应使用各事件自身的时间戳字段存储事件,按等级而非到达顺序比较状态,并让较新的客户消息优先于迟到的较早消息。在 Coexistence 号码上,一次性历史导入可能在入驻前后与实时消息重叠,此时以消息 ID 对二者进行核对。
安全的处理程序是什么样的?
四个步骤:验证、精确返回 200、去重,然后从队列中处理工作,确保 Meta 的请求与你的响应之间不存在任何缓慢操作。此版本使用你自己 Meta 应用的密钥校验 X-Hub-Signature-256;对于通过 easyCoexistence 连接的号码,Meta 使用 easyCoexistence 的应用密钥签名,因此直接投递的目的地应改用 URL 路径中的长密钥进行认证,或改用按号码签名的托管转发。
// 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 作为第二个键保留。
转发至你服务器的内容会经过签名、排队并在失败时重试,每个号码 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,而不是几个月。应用会继续在手机上运行。
开始免费试用验证时间