Интеграции
Webhook не доходит до сайта или возвращает 404
Внешний сервис отправляет webhook, но сайт его не получает или отвечает 404. Разберём адрес, маршрут и подтверждение приёма события.
Что происходит и с чего начать
Webhook — запрос внешней системы на заранее заданный адрес сайта. Он приходит без браузерной сессии пользователя, поэтому обычное открытие адреса вручную не проверяет весь сценарий. Значение имеют метод запроса, точный путь, домен и правила доступа. Начните с одной доставки и её времени. Если сайт возвращает 404, нужно выяснить, какой узел не нашёл маршрут: веб-сервер, приложение или промежуточный прокси. Полная переустановка интеграции до этой проверки обычно не даёт полезной информации.
Что можно проверить самостоятельно
- Сохраните адрес получателя без секретных параметров, время доставки и ответ сервиса. Уточните метод запроса и тип события, если они видны в настройках интеграции.
- Проверьте последние изменения домена, путей и защиты сайта. После переноса старый endpoint может оставаться настроенным во внешнем кабинете, даже если новые страницы работают нормально.
- Посмотрите, есть ли событие в журнале веб-сервера и приложения. Отсутствие записи только в приложении не доказывает, что запрос вообще не дошёл до сервера.
Как понять результаты проверки
Если запрос виден на веб-сервере, но не в приложении, проверяют маршрутизацию и блокировки до обработчика. Если обработчик запустился, исследуют его ответ и сохранение события. Возвращать успех без принятия данных опасно: отправитель может считать доставку завершённой. С другой стороны, повтор должен быть безопасным, если ответ потерялся после сохранения. У корректного получателя есть проверка подлинности, фиксируемый результат приёма и понятная связь между внешним событием и созданной внутренней операцией.
Что проверяет разработчик
Для этой части понадобятся доступ к настройкам, журналам ошибок или коду. Её можно передать специалисту вместе с результатами предыдущих шагов.
- Уточните точный URL, метод, формат тела и время попытки. Сопоставьте их с access log, включая домен и путь.
- Если запрос не найден, проверьте DNS, сертификат и сетевую доступность. Если найден 404, проверьте маршрут именно для нужного метода и завершающего слеша.
- Проверьте, не перехватывают ли запрос авторизация, CSRF или защита. Ответ HTML вместо ожидаемого формата часто указывает на промежуточный слой.
На что обратить внимание
GET по тому же адресу может работать, пока POST попадает в другой маршрут. После изменения домена старый адрес уведомления иногда продолжает использоваться во внешнем кабинете.
Как исправляют причину
Настройте стабильный публичный маршрут и проверку подлинности по контракту сервиса. Сохраняйте событие или результат обработки надёжно до подтверждения приёма и учитывайте повторные доставки.
Как убедиться, что проблема решена
Отправьте предусмотренное сервисом тестовое событие, затем его повтор. Проверьте ответ и бизнес-результат; произвольный JSON без правильной подписи не является полноценным тестом.
Проверьте доставку реального тестового события из кабинета отправителя, а не только ручной запрос разработчика. Найдите его сохранённый результат и повторите доставку, если тестовый механизм это допускает. Убедитесь, что событие не выполняется дважды. Для пропущенного периода согласуйте список восстановления: исправленный адрес принимает новые запросы, но сам по себе не возвращает все события, потерянные раньше.