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

Уведомление 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 бесплатно уже сегодня и откройте доступ к локальному серверу всего одной командой.
Зарегистрироваться бесплатно →По теме

Платёжные вебхуки на localhost: ЮKassa, Т-Банк, Robokassa и CloudPayments
7 сентября 2025 г.
Как проверить доставку платёжного вебхука на локальный сервер: HTTPS-туннель, выбор инструкции провайдера, подпись, повтор и диагностика HTTP-ответов.

Как повторить вебхук: отладка HTTP-запросов через Replay
20 июня 2026 г.
Получите тестовый вебхук, найдите ошибку и повторите запрос после исправления. Рабочий пример на Python, диагностика подписей и ограничения Replay.

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

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