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

{
  "messageId": "2603121407537573731",
  "channel": "SMS",
  "destination": "447700900123",
  "status": "DELIVERED",
  "timestamp": "2026-10-10T09:15:42Z",
  "reason": null
}

Как написать надёжный обработчик?

Сделайте три вещи по порядку: сохраните исходное событие, подтвердите ответом 2xx, затем обработайте асинхронно. Обработчик ниже следует шаблону из нашей документации.

import express from "express";

const app = express();

// Сохраняйте исходное тело, чтобы хранить его точно в том виде, в каком оно получено.
app.post(
  "/webhooks/omnichannels",
  express.json({ verify: (req, _res, buf) => { req.rawBody = buf.toString("utf8"); } }),
  async (req, res) => {
    try {
      await db.webhookEvents.insert({ receivedAt: new Date(), body: req.rawBody });
    } catch (err) {
      return res.sendStatus(500); // хранилище недоступно: пусть событие повторят
    }
    res.sendStatus(200);          // подтверждайте быстро
    queue.publish("status-events", req.body); // основную работу выполняйте в другом месте
  },
);

// Воркер: идемпотентная обработка
async function processEvent(event) {
  const id = event.messageId ?? event.message_id ?? event.id; // сопоставляйте по каналу
  const status = event.status;
  const rank = { SUBMITTED: 1, SENT: 2, DELIVERED: 3, READ: 4, FAILED: 4, REJECTED: 4 };

  const current = await db.messages.findOne({ providerId: id });
  if (!current) return; // неизвестное сообщение: залогируйте и разберитесь
  if ((rank[status] ?? 0) <= (rank[current.status] ?? 0)) return; // дубликат или устаревшее событие

  await db.messages.update({ providerId: id }, { status, updatedAt: new Date() });
}

from datetime import datetime, timezone
from flask import Flask, request

app = Flask(__name__)

RANK = {"SUBMITTED": 1, "SENT": 2, "DELIVERED": 3, "READ": 4, "FAILED": 4, "REJECTED": 4}


@app.post("/webhooks/omnichannels")
def omnichannels_webhook():
    raw = request.get_data(as_text=True)
    try:
        db.webhook_events.insert({"received_at": datetime.now(timezone.utc), "body": raw})
    except Exception:
        return "", 500           # хранилище недоступно: пусть событие повторят
    queue.publish("status-events", raw)  # обрабатывайте асинхронно
    return "", 200               # подтверждайте быстро

Объекты db и queue — ваше собственное хранилище и очередь заданий. Карта rank делает обработку идемпотентной: дубликат или устаревшее событие не продвигает состояние, поэтому игнорируется.

Правила надёжного обработчика

• Отвечайте в течение нескольких секунд. Не выполняйте тяжёлую работу до ответа.
• Возвращайте 2xx только после сохранения события. Если хранилище недоступно, возвращайте 5xx.
• Устраняйте дубликаты по идентификатору сообщения. Один и тот же статус может прийти несколько раз.
• Никогда не отправляйте сообщение повторно из обработчика. Решения о повторах принимайте в отдельном задании, проверив статус.
• Храните исходное тело для разбора проблем и для повторного воспроизведения событий после исправления.

Как защитить вебхук WhatsApp?

Это зависит от того, кто отправляет на ваш эндпоинт. Meta подписывает вебхуки, которые отправляет зарегистрированным вами в Meta приложениям. В спецификации API OmniChannels.ai заголовок подписи вебхука не определён, поэтому не ждите его.

Для схемы Meta документация Meta предписывает сформировать хеш HMAC-SHA256 от JSON-нагрузки с секретом приложения и сравнить его со значением после sha256= в заголовке X-Hub-Signature-256. Сам HMAC определён в RFC 2104. Вычисляйте его над исходными байтами, а не над повторно сериализованным объектом, и сравнивайте за постоянное время.

Для нашего эндпоинта:

• Используйте только HTTPS с действительным сертификатом.
• Используйте длинный неугадываемый путь и меняйте его при утечке.
• Проверяйте структуру тела и отклоняйте всё неожиданное.
• Считайте события уведомлениями. Перед необратимым действием, например возвратом средств или блокировкой по подозрению в фроде, подтвердите состояние запросом.

Что происходит при сбое доставки?

Повторы зависят от отправителя. Документация Meta сообщает, что она повторяет неудачную доставку со всё меньшей частотой до 7 дней, что может приводить к дубликатам уведомлений. Это повод быть идемпотентным, даже если дубликаты вы видите редко. Для событий нашей платформы уточните поведение повторов у инженера по подключению, а не считайте его таким же, как у Meta.

В любом случае проектируйте систему с учётом потери так же, как и дублирования: эндпоинт может быть недоступен при развёртывании, а правило файрвола может молча отбрасывать запросы.

Как восстановить пропущенные события?

Опрашивайте пакет, а не отправляйте сообщение заново.

curl "https://api.broadnet.me/whatsapp/message/bulk-insights?batch_Id=2609091405000000001&page=0&size=100" \
  -H "Authorization: Bearer $BROADNET_TOKEN"

batch_Id — это идентификатор, который вернул вызов отправки, а page нумеруется с нуля. Запускайте ночную сверку, которая читает пакеты за предыдущий день и заполняет пробелы.

Чек-лист диагностики

1. URL настроен в нужном аккаунте или субаккаунте?
2. Эндпоинт доступен по HTTPS с действительным сертификатом?
3. Он быстро отвечает 2xx или срабатывает тайм-аут?
4. Запросы не блокирует правило файрвола или WAF?
5. Вы логируете исходное тело до разбора, чтобы ошибка парсера не скрыла событие?

Пример: конвейер уведомлений ритейлера

«Souq Rafiq» (условный пример), розничный продавец из ОАЭ, отправляет обновления по заказам в WhatsApp и хочет получать точный статус в своей системе заказов.

1. Заказы отправляются через sendbulk, а batchId сохраняется в заказе. См. отправку сообщения WhatsApp через API.
2. Эндпоинт вебхука записывает каждое событие в таблицу, затем возвращает 200.
3. Воркер ранжирует статусы и обновляет состояние сообщения в заказе.
4. События FAILED создают задачу для поддержки с указанием причины, а переход на SMS рассматривается по стратегии резервных каналов.
5. Входящие сообщения клиентов направляются в общий инбокс, чтобы операторы могли ответить внутри окна.
6. Ночное задание вызывает bulk-insights по вчерашним пакетам и исправляет всё пропущенное.

Какие типичные ошибки?

• Тяжёлая работа до ответа, которая вызывает тайм-ауты и повторные доставки.
• Подтверждение до сохранения, из-за которого события теряются при сбое хранилища.
• Доверие порядку. Запоздавший SENT перезаписывает DELIVERED.
• Код под иллюстративный payload вместо реальных событий.
• Повторная сериализация JSON до проверки подписи, которая меняет байты.
• Повторная отправка из обработчика, которая может зациклиться.
• Ограничения: это руководство описывает наше документированное поведение. Политику повторов и поля payload для вашего аккаунта нужно подтвердить при подключении.

Как помогает OmniChannels.ai

OmniChannels.ai отправляет статусы доставки и входящие сообщения WhatsApp, SMS, RCS и других каналов на ваш вебхук в едином нормализованном формате, с отдельными вебхуками на субаккаунты для реселлеров. BroadNet — официальный Meta Business Solution Provider, поэтому собственные требования Meta к вебхукам выполняются за вас, а вы работаете с нашим API. Читайте справочник по вебхукам и документацию WhatsApp API или посмотрите, как события отображаются в общем инбоксе.