Повторы вебхуков WhatsApp, дубликаты и порядок: как с ними работать
Meta повторяет вебхук WhatsApp, который получил что-либо кроме HTTP 200: сразу, а затем всё реже, в течение до 7 дней, после чего отбрасывает его. Повторы уходят всем приложениям, подписанным на аккаунт, поэтому дубликаты нормальны. Отвечайте 200 быстро, дедуплицируйте по id сообщения или по id статуса плюс сам статус и упорядочивайте события по их собственным timestamp.
easyCoexistence подключает ваш номер приложения WhatsApp Business к Cloud API Meta через Coexistence и принимает на себя повторные доставки Meta до того, как их увидят ваши автоматизации, поэтому повторное сообщение не получает второй ИИ-ответ.
Как долго Meta повторяет вебхук, не получивший HTTP 200, прежде чем отбросить его.
Большинство обновлений Meta объединяет в один POST; Meta не обещает пакетной отправки, поэтому обрабатывайте каждый запрос отдельно.
Максимальный размер тела POST-запроса вебхука WhatsApp.
Как долго easyCoexistence помнит id каждого входящего сообщения, чтобы повторно доставленное сообщение не запускало автоматизацию дважды.
Количество попыток на каждую пересылку на ваш Forward URL, каждая ожидает 2xx 10 секунд, в течение примерно 33 часов.
Когда Meta повторяет вебхук WhatsApp?
Всякий раз, когда доставка на ваш эндпоинт получает HTTP-статус, отличный от 200, или вовсе не может быть доставлена. Meta повторяет сразу, затем ещё несколько раз всё реже в течение следующих 7 дней, а неподтверждённое отбрасывает по истечении этого срока. Повторы уходят каждому приложению, подписанному на WhatsApp Business Account для этого поля, поэтому Meta предупреждает, что они могут создавать дублирующие уведомления. API для получения прошлых вебхуков нет, поэтому доставка, не уложившаяся в 7 дней, для вашей системы потеряна.
Почему дубликаты приходят, даже когда сервер исправен?
Потому что доставка может пройти успешно на вашей стороне и всё равно выглядеть для Meta неудачной. Обработчик, который выполняет работу до ответа, может выйти за время ожидания Meta, и Meta повторит то, что вы уже обработали. Деплой, перезапускающий сервер посреди запроса, балансировщик, на миг возвращающий 502, или 201 либо 204 вместо 200 считаются сбоями. Пакеты добавляют ещё один случай: один POST может содержать много обновлений, поэтому тайм-аут большого пакета возвращает весь пакет, включая обновления, которые вы уже обработали.
По какому ключу дедуплицировать?
По собственным id Meta, выбираемым для каждого типа события, потому что одно сообщение законно порождает несколько вебхуков. Ключ статуса без значения статуса будет считать delivered и read копиями sent, а ключ звонка без события сохранит только первый этап звонка. Храните ключи с уникальным индексом, чтобы два рабочих процесса, обрабатывающие один и тот же повтор, не могли оба выиграть:
В каком порядке приходят вебхуки?
Не обязательно в том порядке, в котором всё происходило. Meta не даёт обещаний порядка, повторно доставленный вебхук приходит после более новых, а статус может пропустить шаг: Meta присылает read без delivered, когда сообщение прочитано в момент поступления. Поэтому храните события с их собственным полем timestamp, сравнивайте статусы по рангу, а не по времени прихода, и пусть более позднее сообщение клиента побеждает более раннее, пришедшее с опозданием. На номере Coexistence разовый импорт истории может пересекаться с живыми сообщениями при онбординге, и id сообщения сверяет эти два потока.
Как выглядит безопасный обработчик?
Четыре шага: проверка, ответ ровно 200, дедупликация, затем работа из очереди, чтобы между запросом Meta и вашим ответом ничего медленного не стояло. Эта версия проверяет X-Hub-Signature-256 секретом вашего собственного приложения Meta. Для номера, подключённого через 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 не повторяет доставку из-за того, что ИИ-ответ занял несколько секунд. Id каждого входящего сообщения хранится 7 дней, то есть длину окна повторов Meta, и повторно доставленное сообщение распознаётся и не запускает второй автоматический ответ.
На выходе на ваш Forward URL каждое изменение Meta становится одной доставкой с id в X-EC-Delivery, который остаётся тем же при повторах пересылки: 7 попыток примерно за 33 часа, каждая ждёт 2xx 10 секунд. Изменение, которое Meta повторила сама, пересылается снова под новым id доставки, поэтому дедуплицируйте и по id Meta внутри value.
Распространённые ошибки
- Дедупликация статусов только по id. sent, delivered и read имеют один и тот же wamid, поэтому ключу нужен и статус.
- Обработка до ответа. Медленный обработчик заставляет Meta повторять уже сделанную работу; сначала верните 200, затем работайте из очереди.
- Возврат 201 или 204. Документация Meta считает любой статус, кроме 200, неудачной доставкой и повторяет её.
- Дедупликация пересылок только по X-EC-Delivery. Изменение, которое Meta повторила, приходит под новым id доставки; сохраняйте id Meta как второй ключ.
Пересылки на ваш сервер подписываются, ставятся в очередь и повторяются, а каждый номер отслеживается круглосуточно. От US$ 9 до US$ 0,75 за подключённый номер в месяц, цена снижается по мере добавления номеров, с бесплатным пробным периодом на первые 3 дня.
Часто задаваемые вопросы
Как долго хранить id, которые я уже видел?
Не меньше 7 дней, то есть окна повторов Meta. Доставка, которую Meta повторит на шестой день, должна совпасть со своим ключом, иначе будет обработана как новая.
Что будет с сообщениями клиентов, если мой эндпоинт недоступен несколько дней?
Meta повторяет до 7 дней, а затем отбрасывает вебхуки. На номере Coexistence переписка по-прежнему доступна в приложении WhatsApp Business на телефоне, поэтому бизнес может ответить оттуда.
Можно ли переиграть пропущенные вебхуки?
Не через Meta: API для исторических данных вебхуков нет. Разовый импорт истории номера Coexistence выполняется только при онбординге и не может быть запрошен повторно для того же подключения.
Отправляет ли Meta одно и то же обновление на несколько серверов?
Оно уходит каждому приложению, подписанному на WhatsApp Business Account для этого поля. При переопределении адреса поля сообщений номера уходят на адрес переопределения вместо обратного вызова по умолчанию этого приложения.
Читайте дальше
Готовы начать?
Настройте WhatsApp Coexistence за несколько минут, а не месяцев. Приложение продолжит работать на телефоне.
Начать бесплатный пробный периодПроверено по состоянию на