При подключении WhatsApp Cloud API платформа отправляет GET-запрос проверки. Endpoint должен сравнить verify token и вернуть значение hub.challenge обычным текстом. Если формат, статус или маршрут неверен, подписка webhook не активируется.

Сначала повторите verification-запрос вручную с тестовыми параметрами и проверьте точный HTTP-ответ. До успешного GET нет смысла отлаживать обработку POST-событий сообщений.

Что сделать в первую очередь

  • Убедитесь, что публичный HTTPS-адрес открывается без авторизации и редиректов.
  • Сравните verify token в панели Meta и в переменных окружения символ в символ.
  • Отправьте тестовый GET с hub.mode, hub.verify_token и hub.challenge.
  • Проверьте, что ответ имеет статус 200 и содержит только challenge.

Почему возникает проблема

Симптом обычно появляется не из-за одной настройки. Сначала разделите путь данных на этапы и найдите место, где фактическое поведение расходится с ожидаемым.

  • Маршрут принимает только POST или middleware отклоняет GET.
  • Verify token содержит пробел, старое значение или читается не из той среды.
  • Приложение возвращает JSON вместо исходной строки hub.challenge.
  • Reverse proxy добавляет редирект, блокирует query string или направляет запрос не в тот контейнер.

Пошаговая диагностика

  • Снимите access log прокси и приложения для одного запроса проверки.
  • Зафиксируйте метод, query string, статус, Content-Type и тело ответа.
  • Проверьте сертификат, цепочку доверия и доступность по IPv4 и IPv6.
  • Исключите кеширование verification-ответа на CDN.
  • После GET отдельно проверьте POST и валидацию X-Hub-Signature-256.

Как исправить

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

  • Добавьте отдельный GET-обработчик, сравнивающий токен постоянным по времени способом.
  • Возвращайте hub.challenge как text/plain без HTML-обертки и отладочного вывода.
  • Храните verify token и app secret в защищенных переменных окружения.
  • Разрешите маршрут в reverse proxy и исключите принудительную авторизацию только для webhook.
  • Для POST проверяйте подпись по исходному телу запроса до разбора JSON.

Как проверить результат

  • Панель Meta успешно сохраняет callback URL и подписку.
  • Тестовое сообщение создает один POST с корректной подписью.
  • Повторное событие не создает дубль благодаря уникальному message id.

Как не допустить повторения

  • Добавьте healthcheck webhook-маршрута и уведомление о сериях ошибок.
  • Не меняйте verify token без синхронного обновления панели и приложения.
  • Храните журнал event id, статуса обработки и безопасного текста ошибки.

Частые вопросы

Verify token выдает Meta?

Нет, это выбранная вами секретная строка, одинаково настроенная в панели и приложении.

Можно ли не проверять подпись POST?

Не стоит. Verification GET подтверждает адрес, а подпись POST защищает обработчик от посторонних запросов.

Когда стоит обратиться за помощью

Если запрос не доходит до приложения, нужны журналы CDN, reverse proxy и backend за один момент времени. Секреты в переписку передавать не нужно: достаточно статусов и обезличенных заголовков.

Итог

Webhook WhatsApp надежно работает, когда GET-проверка отделена от безопасной обработки POST. Я могу настроить endpoint, подпись, журнал событий и устойчивую передачу сообщений в CRM.