Почему вебхук не срабатывает — три причины, которые ловят всех

Ты настроил вебхук, дёргаешь событие — и тишина. Кажется, он не срабатывает.

Почти всегда это неправда: вебхук отправился. Просто не доехал до твоего кода — или доехал, но ты его случайно отверг. Хорошая новость: причин, по сути, три, и все чинятся быстро. Пойдём от самой частой.

Симптом: событие есть, а вебхук молчит

Сначала сверим, что вообще происходит. Вебхук — это когда чужой сервис сам стучится на твой URL, как только случилось событие: пришла оплата, кто-то написал боту. Ты дал сервису адрес — он шлёт туда запрос.

«Не срабатывает» может значить три разные вещи: запрос не ушёл, ушёл но не дошёл, дошёл но ты его не принял. Разберём по частоте.

Причина 1 (самая частая): твой URL недоступен снаружи

Девять из десяти — вот это. Ты тестируешь на localhost:3000. Для тебя он открывается. Но вебхук шлёт не твой браузер, а чужой сервер из интернета — а из интернета localhost означает его собственную машину, не твою.

Как проверить: открой свой вебхук-URL с телефона по мобильному интернету (не по домашнему Wi-Fi). Не открылось — значит, и отправитель до него не достучится.

Как починить: дай локальному серверу публичный адрес через туннель. ngrok http 3000 или cloudflared поднимут временный публичный URL, который ведёт на твой localhost. Этот адрес и вставь в настройки вебхука. В проде — просто нормальный домен задеплоенного приложения.

Причина 2: ты не вернул 200 — и отправитель сдался

Вебхук дошёл, твой код отработал — но ты не ответил отправителю «принял». Сервисы ждут в ответ HTTP-код 200. Не дождались — считают доставку проваленной и после нескольких повторов отключают вебхук совсем.

Как проверить: глянь в панели отправителя историю доставок. Красные попытки с кодом 500, 404 или «timeout» — вот твой ответ.

Как починить: в обработчике всегда возвращай 200 — и делай это быстро. Если внутри тяжёлая работа (генерация, письмо), не тяни с ответом: сначала ответь 200, потом делай долгое в фоне. Отправителю нужен факт «дошло», а не результат твоей работы. Тут помогает понимание, как устроен API-запрос и что такое код ответа.

Причина 3: подпись не сходится — ты сам его отверг

Дошёл, ты ответил — но своим же кодом решил, что запрос поддельный, и выкинул. Многие сервисы подписывают вебхук секретом, а ты на своей стороне проверяешь подпись. Не сошлось — код отвечает 401 и игнорит. Вебхук «не сработал», хотя пришёл настоящий.

Как проверить: временно залогируй входящий запрос до проверки подписи. Тело приходит — значит, дело в проверке, а не в доставке.

Как починить: сверь, что секрет в коде совпадает с тем, что в панели сервиса (частая беда — секрет из тестового окружения, а вебхук из боевого). И проверяй подпись по сырому телу запроса: если фреймворк успел распарсить JSON и собрать обратно, байты меняются и подпись не сходится.

Общий приём: смотри логи отправителя

Не гадай на своей стороне. У любого нормального сервиса вебхуков есть журнал доставок: когда отправили, какой код получили в ответ, что было в теле. Это самый быстрый способ понять, на каком из трёх шагов всё встало. Зелёный 200 в журнале, а у тебя пусто — ищи баг у себя. Красный код или пусто — проблема в доставке.

Как протестировать вебхук локально?

Подними туннель (ngrok http 3000) и вставь его URL в настройки вебхука — тогда чужой сервис достучится до твоего localhost. Многие панели дают кнопку «отправить тестовое событие»: жми её и смотри, дошло ли. Это быстрее, чем ждать реального события вроде оплаты. Так же удобно отлаживать и телеграм-бота.

Вебхук пришёл дважды — это баг?

Нет, это норма. Если отправитель не дождался чёткого 200 (или дождался с задержкой), он повторит доставку — и одно событие прилетит дважды. Поэтому обработчик должен быть идемпотентным: повтор того же события не создаёт вторую оплату или второе письмо. Проверяй уникальный id события и пропускай, если уже видел.