Уведомления ЮKassa, которые доходят до бэкенда
ЮKassa шлёт уведомление один раз и повторяет его ограниченное время. Если ваш сервер в этот момент перезагружается или лежит за упавшим прокси, платёж проходит, а заказ остаётся неоплаченным в вашей базе. HookPilot стоит между ЮKassa и вашим бэкендом: принимает уведомление сразу, сохраняет и доставляет столько раз, сколько нужно.
Бесплатный тариф без карты: одно подключение и 10 000 событий в месяц.
Как подключить
Источник ЮKassa считается одним подключением. Эндпоинты, в которые уходят события, считаются отдельно.
- 1
Создайте в кабинете HookPilot источник с провайдером «ЮKassa» и выберите эндпоинты, в которые должны уходить события.
- 2
Скопируйте адрес приёма. В конце адреса стоит секретный токен: вводить в ЮKassa ничего больше не нужно, но и публиковать адрес нельзя, он и есть пароль.
- 3
Вставьте адрес в личном кабинете ЮKassa: Настройки → Уведомления → URL для уведомлений. Отметьте события, которые хотите получать.
- 4
Подпишите эндпоинты на типы событий: например, payment.succeeded и refund.succeeded или маску payment.*.
Что проверяется при приёме
Токен в адресе
У ЮKassa нет подписи тела уведомления, поэтому адрес приёма содержит секретный токен. Он сравнивается с эталоном за постоянное время, уведомление на адрес без токена или с чужим токеном отклоняется.
Сети ЮKassa
Уведомление принимается только с адресов из официального списка ЮKassa, включая диапазон IPv6. Запрос с любого другого адреса отклоняется ещё до разбора тела.
Идентификатор объекта
Поле object.id становится внешним идентификатором события. Если ЮKassa пришлёт то же уведомление второй раз, второй вебхук не создастся.
Ответ сразу
ЮKassa получает 200 в момент сохранения события, а не после того, как ответил ваш бэкенд. Доставка в бэкенд идёт отдельно и повторяется по расписанию.
Событие не пришло
Три причины, которые встречаются чаще остальных. Всё принятое видно в ленте принятого в кабинете вместе с типом и историей доставки.
ЮKassa показывает ошибку доставки
Проверьте, что адрес скопирован целиком вместе с токеном и источник активен. Адрес доступен снаружи по HTTPS, отвечаем мы, а не ваш сервер, поэтому состояние бэкенда на этот шаг не влияет.
Событие принято, вебхука нет
Эндпоинт не подписан на этот тип события. Откройте ленту принятого: там видно тип каждого события и в какие эндпоинты оно ушло.
Уведомление отклонено
Токен в адресе не совпал или запрос пришёл не из сетей ЮKassa. Первое бывает после пересоздания источника, второе, если между ЮKassa и нами стоит ваш прокси. Отправляйте уведомления напрямую.
Нужно ли самим отвечать ЮKassa кодом 200?
Нет. HookPilot отвечает ЮKassa сразу после сохранения события. Ваш бэкенд получает вебхук отдельно, и если он не ответил, доставка повторяется до восьми раз почти за двое суток.
Что делать, если адрес приёма попал в чужие руки?
Пересоздайте источник: у нового будет другой токен и другой адрес. Обновите адрес в кабинете ЮKassa и удалите старый источник.
Можно ли отдать одно уведомление в несколько систем?
Да. Источник подключается к любому числу эндпоинтов: основной бэкенд, аналитика, стенд для отладки. Каждый получает свою доставку со своими повторами.
Другие интеграции
Платёжные системы, маркетплейсы и любая система с подписанными вебхуками или HTTP API.