Проверка эндпоинта вебхука WhatsApp
До доставки любого события Meta вызывает ваш эндпоинт запросом GET с hub.mode, hub.verify_token и hub.challenge. Эндпоинт должен проверить токен и вернуть challenge как необработанное тело ответа. При любом другом ответе доставка не начнётся.
Значение, которое нужно вернуть в теле ответа.
Значение hub.mode в запросе проверки.
Единственная схема, которую проверяет Meta. HTTP отклоняется до вызова.
Что именно отправляет Meta?
GET-запрос на ваш URL с тремя параметрами запроса. hub.mode получает значение subscribe. hub.verify_token содержит токен, который вы указали при настройке назначения. hub.challenge содержит значение, созданное Meta для этой попытки.
Эндпоинт должен сравнить hub.verify_token с выбранным вами токеном и, если они совпадают, вернуть ответ 200, где всё тело ответа состоит из hub.challenge. Без JSON, без кавычек вокруг значения и без завершающего переноса строки, который некоторые фреймворки добавляют по умолчанию.
Если токены не совпадают, верните ответ 403. Таков весь протокол, и он намеренно прост.
Почему неверный ответ не вызывает ошибку?
Потому что сбой проверки не является ошибкой в вашей системе, а означает отсутствие назначения в системе Meta.
Если challenge возвращён неправильно, Meta просто не начинает доставку на это назначение. Ваш сервер отвечает 200 на проверку, в журналах виден входящий запрос, а ни одна панель управления не сообщает о проблеме. Единственный признак: сообщения не приходят. Обычно это принимают за проблему Coexistence, а не за проблему рукопожатия.
Поэтому проверку до вызова стоит выполнять заранее. Мы проверяем, что URL использует HTTPS и что токен проверки указан, до отправки запроса к Graph. Некорректное назначение сразу завершается ошибкой, а не выглядит подключённым.
Что ещё может заблокировать проверку?
Три причины, не связанные с кодом.
Аутентификация перед эндпоинтом. Шлюз, базовая аутентификация или список разрешённых IP отклонят запрос Meta, а Meta не может предоставить учётные данные. Маршрут проверки должен быть доступен без них.
Перенаправление. Meta вызывает указанный вами URL, а переход 301 на канонический хост не выполняется так, чтобы рукопожатие завершилось. Укажите конечный URL.
И фреймворк, который сериализует ответ. Если обработчик возвращает строку, а фреймворк оборачивает всё в JSON, тело будет содержать кавычки вокруг challenge и не совпадёт с ожидаемым значением.
Распространённые ошибки
- Возвращать JSON. Тело должно содержать только необработанное значение challenge.
- Размещать эндпоинт за аутентификацией. У Meta нет учётных данных, поэтому запрос будет отклонён.
- Указывать Meta URL с перенаправлением. Используйте конечный URL.
EasyCoexistence проверяет HTTPS и наличие токена проверки до вызова Meta, а неудачное рукопожатие записывает в хронологию подключения вместо удаления назначения.
Часто задаваемые вопросы
Какой токен использовать?
Любую выбранную вами строку. Она позволяет эндпоинту отличить запрос Meta от запросов других людей, узнавших URL.
Как часто выполняется проверка?
При настройке и при каждом указании назначения. Работающий эндпоинт не проверяется повторно при каждом событии.
Могу ли я проверить это самостоятельно?
Да. Вызовите свой эндпоинт с тремя параметрами и проверьте, что тело ответа в точности совпадает со значением challenge.
Что, если мой сервер был недоступен во время проверки?
Рукопожатие завершится ошибкой, и назначение не активируется. Повторное сохранение запускает проверку заново.
Читайте дальше
Готовы начать?
Настройте WhatsApp Coexistence за несколько минут, а не месяцев. Приложение продолжит работать на телефоне.
Начать бесплатный пробный периодПроверено по состоянию на