TunnelHunt

Вебхуки ЮKassa на localhost: HTTPS и проверка платежа через API

4 мин чтения

Принимаем уведомления ЮKassa в локальном Flask: публичный HTTPS, проверка платежа через API, повторные события и диагностика HTTP-ответов.

Уведомление ЮKassa через HTTPS-туннель и проверка платежа сервером

Чтобы отладить уведомления ЮKassa на localhost, запустите обработчик, откройте его через HTTPS-туннель и укажите публичный URL в настройках тестового магазина. Полученное тело запроса нельзя использовать как единственное доказательство оплаты: пример ниже получает платёж из API вашего магазина.

Что понадобится

  • Python 3.10 или новее, SSH-клиент и отдельный тестовый магазин ЮKassa.
  • ID магазина и секретный ключ для серверного API. Не используйте рабочие платёжные данные.
  • Два терминала: для Flask и SSH. Входящий порт на домашнем роутере открывать не нужно.

Это диагностический обработчик: он показывает проверенный статус, но не выдаёт товары и не меняет заказы.

1. Запустите обработчик

Установите зависимости в отдельное окружение:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install 'Flask>=3.1,<4' 'requests>=2.32,<3'
export YOOKASSA_SHOP_ID='ID_ТЕСТОВОГО_МАГАЗИНА'
export YOOKASSA_SECRET_KEY='СЕКРЕТНЫЙ_КЛЮЧ_ТЕСТОВОГО_МАГАЗИНА'

В PowerShell используйте .venv\Scripts\Activate.ps1 и переменные $env:YOOKASSA_SHOP_ID, $env:YOOKASSA_SECRET_KEY.

Сохраните как app.py:

import os
from uuid import UUID

import requests
from flask import Flask, request

app = Flask(__name__)
app.config['MAX_CONTENT_LENGTH'] = 64 * 1024
SHOP_ID = os.environ['YOOKASSA_SHOP_ID']
SECRET_KEY = os.environ['YOOKASSA_SECRET_KEY']
EVENT_STATUS = {
    'payment.succeeded': 'succeeded',
    'payment.waiting_for_capture': 'waiting_for_capture',
    'payment.canceled': 'canceled',
}


@app.post('/webhook/yookassa')
def webhook():
    data = request.get_json(silent=True)
    if not isinstance(data, dict) or data.get('type') != 'notification':
        return 'Invalid notification', 400
    event = data.get('event')
    if not isinstance(event, str) or event not in EVENT_STATUS:
        return 'Unsupported event', 400
    obj = data.get('object')
    if not isinstance(obj, dict) or not isinstance(obj.get('id'), str):
        return 'Invalid payment id', 400
    try:
        payment_id = str(UUID(obj['id']))
    except ValueError:
        return 'Invalid payment id', 400

    try:
        response = requests.get(
            f'https://api.yookassa.ru/v3/payments/{payment_id}',
            auth=(SHOP_ID, SECRET_KEY), timeout=10,
        )
        response.raise_for_status()
        payment = response.json()
    except (requests.RequestException, ValueError):
        return 'Payment verification unavailable', 502
    if not isinstance(payment, dict) or payment.get('id') != payment_id:
        return 'Unexpected API response', 502
    if payment.get('status') not in EVENT_STATUS.values():
        return 'Unexpected payment status', 502
    if payment.get('status') != EVENT_STATUS[event]:
        # Состояние могло измениться после отправки старого уведомления.
        return 'Old event ignored', 200
    if event == 'payment.succeeded' and payment.get('paid') is not True:
        return 'Unexpected payment state', 502

    # Данные берём из API, а не из непроверенного object вебхука.
    print('Verified payment:', payment_id, payment['status'])
    # В этом примере заказ НЕ помечается оплаченным.
    return 'OK', 200


if __name__ == '__main__':
    app.run(host='127.0.0.1', port=8000, debug=False)

Запустите python app.py. Обработчик слушает http://127.0.0.1:8000/webhook/yookassa. Не включайте интерактивный Flask debugger на публичном адресе.

Почему здесь нет проверки «цифровой подписи»

Для этих уведомлений ЮKassa документирует проверку актуального объекта и IP отправителя. Сети нужно проверять точно через ipaddress, а заголовкам прокси доверять только при известной конфигурации. Проверка префикса вроде 185.71.76. разрешает лишние адреса и пропускает другие действующие диапазоны. Мы выбрали серверный GET платежа, чтобы пример не зависел от передачи исходного IP через туннель. Официальные уведомления ЮKassa.

Сам GET не доказывает, кто прислал входящий запрос. Он позволяет сверить платёж по доверенному серверному источнику. Перед выдачей товара дополнительно сопоставьте ID с созданным вами заказом, сумму, валюту и магазин; изменение заказа должно быть атомарным и идемпотентным. Не принимайте эти значения из одного входящего JSON.

2. Получите публичный HTTPS

В другом терминале:

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

Скопируйте выданный адрес и добавьте путь /webhook/yookassa, например https://YOUR-SUBDOMAIN.tunnelhunt.ru/webhook/yookassa. Оставьте оба процесса запущенными. Без регистрации сессия ограничена 15 минутами; для более долгой проверки добавьте SSH-ключ в бесплатный аккаунт.

3. Настройте тестовый магазин

Откройте настройки HTTP-уведомлений в тестовом магазине, задайте полученный URL и выберите payment.succeeded, payment.waiting_for_capture, payment.canceled. Настройки интерфейса могут отличаться; ориентируйтесь на инструкцию ЮKassa.

Проведите платёж в тестовом режиме. Результат успешной проверки: входящий POST виден в журнале TunnelHunt, локальная консоль выводит Verified payment, а обработчик возвращает HTTP 200. Не рассчитывайте на автоматический «пинг» после сохранения URL: проверяйте доставку реального тестового события.

4. Проверьте ошибки и повтор

Результат Что проверить
400 JSON, type, поддерживаемое событие и UUID платежа
502 от обработчика Ключи тестового магазина, доступ к API, HTTP-статус API
502 от туннеля Flask и SSH работают, порт указан правильно
200 с Old event ignored У платежа уже другой текущий статус; бизнес-действие не выполнено
Нет входящего запроса URL тестового магазина, событие и срок SSH-сессии

Повторите запрос через Replay в кабинете. Если событие устарело, API вернёт текущий статус и пример пропустит его. Если обработчик ранее ответил ошибкой, ЮKassa также повторяет доставку; успешное получение подтверждается HTTP 200. Правила доставки.

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

Как сохранить адрес между тестами

При повторяющихся проверках можно закрепить поддомен на Pro, чтобы не менять URL уведомлений после переподключения. Это сохраняет имя, но компьютер и SSH должны оставаться включёнными. См. общую инструкцию по платёжным вебхукам и диагностику localhost.

Проверьте уведомление тестового магазина ЮKassa

Запустите обработчик и сверку платежа через API, затем проверьте тестовое событие. Поддомен Pro сохранит URL уведомлений после переподключения.

Первый запуск: добавьте публичный SSH-ключ, запустите локальное приложение и команду SSH из статьи, затем откройте выданный HTTPS-адрес. Если ответа нет, пройдите проверку localhost и туннеля.

Free: 1 ГБ трафика в месяц, 1 туннель, сессия до 4 часов. Pro: 199 ₽/месяц, 50 ГБ, до 5 туннелей и резервирование поддомена. Компьютер, приложение и SSH-соединение должны работать; постоянный адрес сохраняет имя, а не доступность выключенного сервера.

Готовы запустить свой первый туннель?

Начните использовать TunnelHunt бесплатно уже сегодня и откройте доступ к локальному серверу всего одной командой.

Зарегистрироваться бесплатно →

По теме

Локальная проверка платёжного вебхука через HTTPS-туннель

Платёжные вебхуки на localhost: ЮKassa, Т-Банк, Robokassa и CloudPayments

7 сентября 2025 г.

Как проверить доставку платёжного вебхука на локальный сервер: HTTPS-туннель, выбор инструкции провайдера, подпись, повтор и диагностика HTTP-ответов.

Читать далее →
Проверка подписи уведомления CloudPayments на локальном сервере

CloudPayments на localhost: Content-HMAC, Pay и проверка вебхука

22 июня 2026 г.

Проверяем Pay-уведомление CloudPayments в Flask: Content-HMAC от исходного тела, form-параметры, подписанный тестовый запрос и диагностика 403.

Читать далее →
Проверка ResultURL Robokassa через локальный обработчик и HTTPS-туннель

Robokassa ResultURL на localhost: подпись, OK и повтор уведомления

22 июня 2026 г.

Проверяем ResultURL Robokassa локально: Flask, подпись MD5 с Password 2 и Shp_, сумма счёта, ответ OK и диагностика через HTTPS-туннель.

Читать далее →
Как открыть localhost в интернете: публичный HTTPS через SSH

Как запустить localhost и открыть сайт в интернете через SSH

11 сентября 2026 г.

Запуск сайта на localhost:3000, проверка в браузере и с телефона, публичный HTTPS через SSH. Пример на Python, настройка Docker и Vite, диагностика ошибок.

Читать далее →