Локальное тестирование вебхуков ЮKassa (YooKassa) через TunnelHunt

Интеграция ЮKassa (ранее Яндекс.Касса) требует надежной обработки уведомлений о платежах (вебхуков). Вебхуки сообщают вашему серверу, когда пользователь успешно оплатил заказ, когда платеж отменен или оформлен возврат.

Отлаживать это локально бывает трудно, ведь ЮKassa не может отправить HTTP-запрос на ваш localhost. В этом гайде мы настроим прием вебхуков ЮKassa на вашем компьютере с помощью TunnelHunt за несколько простых шагов.

---

Шаг 1: Пишем обработчик вебхуков (Python / Flask)

Для начала создадим локальный сервер, который будет ловить POST-запросы от ЮKassa.

[!TIP] В macOS Monterey и новее порт 5000 зарезервирован под AirPlay Receiver. Во избежание ошибок Address already in use мы запустим наш Flask-сервер на порту 8000.

Создайте файл app.py:

# app.py
from flask import Flask, request, abort

app = Flask(__name__)

# ЮKassa присылает вебхуки с этих подсетей
ALLOWED_YOO_IPS = ('185.71.76.', '185.71.77.', '185.71.78.', '185.71.79.')

@app.route('/webhook/yookassa', methods=['POST'])
def yookassa_webhook():
    # 1. Проверка безопасности по IP-адресу
    # Так как TunnelHunt работает как прокси, оригинальный IP будет в X-Forwarded-For
    client_ip = request.headers.get('X-Forwarded-For', request.remote_addr)
    
    if not any(client_ip.startswith(prefix) for prefix in ALLOWED_YOO_IPS):
        print(f"🚨 Попытка несанкционированного доступа с IP: {client_ip}")
        abort(403) # Отклоняем запрос

    # 2. Обработка JSON-уведомления
    if request.is_json:
        event_data = request.get_json()
        event_type = event_data.get('event')
        payment_obj = event_data.get('object', {})
        
        print(f"🎉 Получено событие от ЮKassa: {event_type}")
        print(f"ID платежа: {payment_obj.get('id')}")
        print(f"Сумма: {payment_obj.get('amount', {}).get('value')} {payment_obj.get('amount', {}).get('currency')}")
        
        # ЮKassa ожидает ответ 200 OK
        return 'OK', 200
    else:
        return 'Bad Request', 400

if __name__ == '__main__':
    app.run(port=8000, debug=True)

Запустите сервер:

pip install Flask
python app.py

Теперь наш сервер слушает адрес http://localhost:8000/webhook/yookassa.

---

Шаг 2: Запускаем туннель TunnelHunt

Сделаем порт 8000 доступным из интернета. Откройте новый терминал и выполните одну команду:

ssh -R 80:localhost:8000 -p 2222 tunnelhunt.ru

В консоли вы увидите сгенерированный публичный HTTPS-адрес, например: https://sleepy-owl.tunnelhunt.ru

Now любой запрос на https://sleepy-owl.tunnelhunt.ru/webhook/yookassa будет мгновенно перенаправлен на ваше локальное Flask-приложение.

---

Шаг 3: Настраиваем личный кабинет ЮKassa

Чтобы ЮKassa знала, куда отправлять события:

1. Войдите в Личный кабинет ЮKassa.
2. Перейдите в раздел Интеграция → Ключи и вебхуки (или настройки уведомлений в тестовом режиме).
3. Включите тумблер получения уведомлений.
4. В поле URL для уведомлений вставьте ваш адрес от TunnelHunt: https://sleepy-owl.tunnelhunt.ru/webhook/yookassa
5. Выберите типы событий, которые хотите отслеживать. Минимальный рабочий набор:
   • payment.succeeded — платеж успешно подтвержден.
   • payment.waiting_for_capture — платеж авторизован (для двухстадийной оплаты).
   • payment.canceled — платеж отменен.
6. Сохраните изменения. ЮKassa отправит тестовый пинг на ваш URL, и в консоли Flask вы увидите успешный входящий запрос.

---

Шаг 4: Тестирование оплаты

Сделайте тестовый платеж на вашем сайте. В момент завершения транзакции ЮKassa отправит POST-запрос, который пройдет через TunnelHunt и отобразится в вашей консоли разработки.

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

---

Секретное оружие: Request Replay в TunnelHunt

Если в обработчике возникла ошибка (например, опечатка в имени переменной), вам не нужно заново проходить весь цикл оплаты на тестовой форме ЮKassa.

Перейдите в личный кабинет TunnelHunt в раздел Logs:

1. Найдите упавший запрос от ЮKassa.
2. Проверьте тело запроса и заголовки.
3. Нажмите кнопку Replay (Повторить запрос).
4. TunnelHunt отправит исходное тело запроса на ваш сервер еще раз, позволяя тестировать исправления за долю секунды.