TunnelHunt

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

5 мин чтения

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

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

Уведомление CloudPayments можно принять на своём компьютере: локальный Flask проверяет подпись, а HTTPS-туннель передаёт запрос провайдера. Сначала проверим обработчик искусственным подписанным запросом, затем подключим отдельный тестовый сайт CloudPayments.

Инструкция посвящена Pay-уведомлению методом POST с form-параметрами. Check, возвраты и подтверждение двухстадийного платежа имеют другую бизнес-логику; не направляйте все события в один обработчик успешной оплаты.

Какие заголовки действительно присылает CloudPayments

Официальная документация проверки уведомлений указывает Content-HMAC и X-Content-HMAC. Алгоритм — HMAC-SHA256, результат кодируется в Base64. Заголовок с именем Content-HMAC-SHA256 в этой схеме не используется.

Content-HMAC относится к исходным URL-encoded параметрам, X-Content-HMAC — к decoded-представлению. Ниже проверяем только Content-HMAC по исходным байтам тела POST. Не декодируйте форму до вычисления подписи и не собирайте строку заново из словаря: пробелы, %-последовательности и порядок параметров имеют значение.

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

Нужны Python 3.10+, SSH-клиент и отдельные тестовые настройки CloudPayments. Создайте окружение:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install 'Flask>=3.1,<4'
export CP_API_SECRET='API_SECRET_ТЕСТОВОГО_САЙТА'

В PowerShell активируйте .venv\Scripts\Activate.ps1 и задайте секрет через $env:CP_API_SECRET. Не сохраняйте API Secret в коде или репозитории.

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

import base64
import binascii
import hashlib
import hmac
import os
from decimal import Decimal, InvalidOperation

from flask import Flask, request

app = Flask(__name__)
app.config['MAX_CONTENT_LENGTH'] = 64 * 1024
API_SECRET = os.environ['CP_API_SECRET']
if not API_SECRET:
    raise ValueError('CP_API_SECRET must not be empty')


def verify_cloudpayments_signature(raw_body, signature, secret):
    if not isinstance(signature, str) or len(signature) > 64:
        return False
    try:
        received = base64.b64decode(signature, validate=True)
    except (ValueError, binascii.Error):
        return False
    expected = hmac.new(secret.encode('utf-8'), raw_body, hashlib.sha256).digest()
    return hmac.compare_digest(expected, received)


@app.post('/webhook/cloudpayments/pay')
def pay():
    raw_body = request.get_data()
    if not verify_cloudpayments_signature(
            raw_body, request.headers.get('Content-HMAC'), API_SECRET):
        return 'Invalid signature', 403
    if request.mimetype != 'application/x-www-form-urlencoded':
        return 'Expected form parameters', 415
    form = request.form
    required = ('TransactionId', 'Amount', 'Currency', 'InvoiceId')
    if any(len(form.getlist(key)) != 1 or not form[key] for key in required):
        return 'Missing or duplicate field', 400
    if not form['TransactionId'].isascii() or not form['TransactionId'].isdigit():
        return 'Invalid TransactionId', 400
    try:
        amount = Decimal(form['Amount'])
        if not amount.is_finite() or amount <= 0:
            return 'Invalid Amount', 400
    except InvalidOperation:
        return 'Invalid Amount', 400
    # Учебный endpoint: подтверждает приём, не меняет заказ и не выдаёт товар.
    app.logger.info('Verified Pay notification: %s', form['TransactionId'])
    return {'code': 0}, 200


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

В этом примере InvoiceId обязателен: передайте номер собственного тестового заказа при создании платежа. Уведомление без него будет отклонено намеренно. Запустите python app.py.

2. Проверьте подпись без платежа

В другом терминале с тем же тестовым CP_API_SECRET задайте тело и вычислите подпись:

export PAY_BODY='TransactionId=100000001&Amount=10.00&Currency=RUB&InvoiceId=demo-order-1'
SIGNATURE=$(python -c 'import os,hmac,hashlib,base64; print(base64.b64encode(hmac.new(os.environ["CP_API_SECRET"].encode(), os.environ["PAY_BODY"].encode(), hashlib.sha256).digest()).decode())')
curl -i http://127.0.0.1:8000/webhook/cloudpayments/pay \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H "Content-HMAC: ${SIGNATURE}" \
  --data-raw "$PAY_BODY"

Ожидаются HTTP 200 и {"code":0}. Уберите заголовок — получите 403. Измените Amount на 99.00, оставив прежнюю подпись, — также 403. Это проверяет защиту тела запроса; реальная доставка из CloudPayments проверяется отдельно.

3. Откройте публичный HTTPS-адрес

Для Free добавьте публичный SSH-ключ в кабинет, затем выполните:

ssh -p 2222 -o ExitOnForwardFailure=yes \
  -R 80:127.0.0.1:8000 tunnelhunt.ru

Скопируйте HTTPS-адрес из терминала. Повторите подписанный запрос через https://YOUR-SUBDOMAIN.tunnelhunt.ru/webhook/cloudpayments/pay. Ответ должен совпасть с локальной проверкой. Если локально 200, а снаружи 502, проверьте порт и работающий SSH; начать можно с диагностики localhost.

4. Подключите тестовый сайт CloudPayments

В настройках уведомлений отдельного тестового сайта включите Pay, укажите полный URL обработчика и метод POST. Используйте формат уведомлений CloudPayments; формат запросов к платёжному API и формат уведомлений — разные настройки. Не выбирайте JSON по аналогии с API: этот обработчик специально принимает form-body.

Проведите тестовую оплату собственного заказа с InvoiceId. Проверьте одновременно событие у провайдера, HTTP 200 / code: 0 и запись с TransactionId в локальном журнале. Не используйте рабочие платежи для отладки.

Симптом Что проверить
403 Правильный API Secret сайта, заголовок Content-HMAC, исходные байты тела
Есть только X-Content-HMAC Проверьте доставленные заголовки и правила decoded-представления; не подставляйте этот заголовок в raw-body проверку
415 Отправлен неподдерживаемый формат вместо form-параметров
400 InvoiceId, числовая сумма, TransactionId и отсутствие дубликатов полей
200, но заказ не меняется Пример только проверяет уведомление; бизнес-операция не реализована
Повтор не проходит после смены секрета Старое тело и подпись относятся к прежнему ключу

Повтор уведомления и рабочий обработчик

Для отладки найдите запрос в Logs кабинета и используйте Replay. Повтор сохраняет смысл прежнего события: это не новая оплата. Учебный endpoint можно вызвать несколько раз, он не выдаёт товар и не создаёт финансовых операций.

В рабочем обработчике найдите собственный заказ, проверьте сумму и валюту, нужный тип уведомления и состояние платежа. Изменение заказа и фиксацию обработанного события выполняйте атомарно; повтор Pay с тем же TransactionId не должен повторно выдавать товар. Не используйте один TransactionId как ключ для всех типов событий: возврат и подтверждение — отдельные переходы состояния. Подтверждайте приём только после сохранения результата или надёжной постановки в свою очередь.

Случайный адрес подходит для первой проверки. Для повторных тестов зарезервированный поддомен Pro сохраняет URL уведомления между подключениями. Он не поддерживает работу выключенного компьютера и не заменяет восстановление SSH.

Проверьте Pay-уведомление CloudPayments

Сначала получите HTTP 200 на искусственном подписанном запросе, затем повторите его по HTTPS. Добавьте SSH-ключ для Free; постоянный адрес 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-ответов.

Читать далее →
Как повторить вебхук: отладка HTTP-запросов через Replay

Как повторить вебхук: отладка HTTP-запросов через Replay

20 июня 2026 г.

Получите тестовый вебхук, найдите ошибку и повторите запрос после исправления. Рабочий пример на Python, диагностика подписей и ограничения Replay.

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

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

22 июня 2026 г.

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

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

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

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

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

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