ВойтиНачать бесплатный пробный период
Meta Tech Provider

Повторы вебхуков WhatsApp, дубликаты и порядок: как с ними работать

Meta повторяет вебхук WhatsApp, который получил что-либо кроме HTTP 200: сразу, а затем всё реже, в течение до 7 дней, после чего отбрасывает его. Повторы уходят всем приложениям, подписанным на аккаунт, поэтому дубликаты нормальны. Отвечайте 200 быстро, дедуплицируйте по id сообщения или по id статуса плюс сам статус и упорядочивайте события по их собственным timestamp.

easyCoexistence подключает ваш номер приложения WhatsApp Business к Cloud API Meta через Coexistence и принимает на себя повторные доставки Meta до того, как их увидят ваши автоматизации, поэтому повторное сообщение не получает второй ИИ-ответ.

7 days

Как долго Meta повторяет вебхук, не получивший HTTP 200, прежде чем отбросить его.

1,000

Большинство обновлений Meta объединяет в один POST; Meta не обещает пакетной отправки, поэтому обрабатывайте каждый запрос отдельно.

3 MB

Максимальный размер тела POST-запроса вебхука WhatsApp.

7 days

Как долго easyCoexistence помнит id каждого входящего сообщения, чтобы повторно доставленное сообщение не запускало автоматизацию дважды.

7 attempts

Количество попыток на каждую пересылку на ваш 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, а ключ звонка без события сохранит только первый этап звонка. Храните ключи с уникальным индексом, чтобы два рабочих процесса, обрабатывающие один и тот же повтор, не могли оба выиграть:

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.

В каком порядке приходят вебхуки?

Не обязательно в том порядке, в котором всё происходило. Meta не даёт обещаний порядка, повторно доставленный вебхук приходит после более новых, а статус может пропустить шаг: Meta присылает read без delivered, когда сообщение прочитано в момент поступления. Поэтому храните события с их собственным полем timestamp, сравнивайте статусы по рангу, а не по времени прихода, и пусть более позднее сообщение клиента побеждает более раннее, пришедшее с опозданием. На номере Coexistence разовый импорт истории может пересекаться с живыми сообщениями при онбординге, и id сообщения сверяет эти два потока.

Как выглядит безопасный обработчик?

Четыре шага: проверка, ответ ровно 200, дедупликация, затем работа из очереди, чтобы между запросом Meta и вашим ответом ничего медленного не стояло. Эта версия проверяет X-Hub-Signature-256 секретом вашего собственного приложения Meta. Для номера, подключённого через 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 не повторяет доставку из-за того, что ИИ-ответ занял несколько секунд. 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 как второй ключ.
Настройка с EasyCoexistence

Пересылки на ваш сервер подписываются, ставятся в очередь и повторяются, а каждый номер отслеживается круглосуточно. От US$ 9 до US$ 0,75 за подключённый номер в месяц, цена снижается по мере добавления номеров, с бесплатным пробным периодом на первые 3 дня.

Часто задаваемые вопросы

Как долго хранить id, которые я уже видел?

Не меньше 7 дней, то есть окна повторов Meta. Доставка, которую Meta повторит на шестой день, должна совпасть со своим ключом, иначе будет обработана как новая.

Что будет с сообщениями клиентов, если мой эндпоинт недоступен несколько дней?

Meta повторяет до 7 дней, а затем отбрасывает вебхуки. На номере Coexistence переписка по-прежнему доступна в приложении WhatsApp Business на телефоне, поэтому бизнес может ответить оттуда.

Можно ли переиграть пропущенные вебхуки?

Не через Meta: API для исторических данных вебхуков нет. Разовый импорт истории номера Coexistence выполняется только при онбординге и не может быть запрошен повторно для того же подключения.

Отправляет ли Meta одно и то же обновление на несколько серверов?

Оно уходит каждому приложению, подписанному на WhatsApp Business Account для этого поля. При переопределении адреса поля сообщений номера уходят на адрес переопределения вместо обратного вызова по умолчанию этого приложения.

Читайте дальше

Статусы вебхуков WhatsApp: отправлено, доставлено, прочитано, ошибкаКак WhatsApp сообщает о судьбе отправленного сообщения: массив statuses, значения статусов, поля и сопоставление по wamid.Почему сообщение WhatsApp не доставлено: чтение статуса failed и его ошибокСтатус failed значит, что Meta не смогла отправить или доставить сообщение. Разберите массив errors и коды 131047, 131049, 131050 и что делать.Вебхук messagesЧто несёт полезная нагрузка, как подтвердить получение и почему поле не попадает к провайдеру на маршрутизированном номере.Как сообщения WhatsApp доходят до вашего сервера: напрямую или через управляемый режим, и проверка подписиНапрямую: Meta шлёт вебхуки на ваш сервер. Через сервис: автоматизации отвечают, подписанная копия уходит на Forward URL.Проверка эндпоинта вебхука WhatsAppMeta отправляет на ваш эндпоинт GET-проверку до доставки событий. Что приходит, что вернуть и почему неверный ответ не вызывает ошибки.Вебхуки WhatsApp: маршрутизация сообщений на ваш серверКак работают вебхуки WhatsApp, что отправляет Meta и как направить входящие сообщения прямо на ваш эндпоинт, минуя платформу провайдера.

Готовы начать?

Настройте WhatsApp Coexistence за несколько минут, а не месяцев. Приложение продолжит работать на телефоне.

Начать бесплатный пробный период

Проверено по состоянию на