Проверка вебхуков криптоплатежей по HMAC в Node, PHP и Python

Рабочая проверка подписи вебхука криптоплатежей на Node, PHP и Python и разбор ошибок, из-за которых настоящая подпись не сходится, а поддельная проходит.

11.11.202612 мин чтения
Webhook request with a signature header and JSON payload, marked signature verified and 200 OK

Вебхук криптоплатежей проверяют так: считают HMAC-SHA256 от сырого тела запроса, байт в байт как оно пришло, ключом служит API-секрет магазина, и сравнивают результат с заголовком подписи функцией постоянного времени. JSON разбирают только после того, как подпись сошлась. Обработчик при этом должен быть идемпотентным: одно и то же событие может прийти несколько раз.

На бумаге это три строки кода. На практике интеграции ломаются на мелочах. Фреймворк успевает распарсить JSON раньше вас, в секрете из .env остаётся перевод строки, подпись сравнивают обычным ==, а повторная доставка выдаёт товар второй раз.

Ниже готовый код для Node (Express), PHP и Python (Flask, FastAPI). В качестве примера взят формат вебхуков Zypher, но схема та же у любого криптопроцессинга, который подписывает тело запроса через HMAC.

Что приходит в вебхуке криптоплатежей

Когда счёт оплачен, на URL вебхука, указанный в настройках магазина, приходит POST с JSON. У Zypher тело выглядит так (полный список полей есть в документации API):

{
  "event": "invoice.paid",
  "data": {
    "invoiceId": "5f0c3a52-7b1e-4f6a-9d2e-0c1b7a9e4d11",
    "orderId": "order-123",
    "status": "PAID",
    "currency": "USDT",
    "network": "tron",
    "amount": "100.00",
    "paidAmount": "100.00"
  },
  "timestamp": 1767226500000
}

И два заголовка:

ЗаголовокЧто в нём
X-Webhook-SignatureHMAC-SHA256 от сырого тела в hex, ключ — API-секрет магазина
X-Webhook-Eventимя события, invoice.paid

В data.status приходит PAID или OVERPAID. Откуда берётся переплата и что делать с недоплатой, разобрано в статье про недоплату, переплату и просроченные счета.

Что подпись гарантирует, а что нет:

  • Гарантирует, что отправитель знает ваш секрет и что тело не меняли по дороге.

  • Не гарантирует, что запрос свежий и что вы не обработали его раньше. Для этого нужны отдельные проверки: метка времени и идемпотентность.

Порядок проверки

  1. Прочитать тело как байты, ничего не парсить.

  2. Посчитать HMAC-SHA256(ключ = apiSecret, сообщение = тело) и перевести в hex.

  3. Взять X-Webhook-Signature. Нет заголовка — отказ.

  4. Сравнить за постоянное время. Не совпало — 401, дальше не идём.

  5. Разобрать JSON. Событие, которое вы не обрабатываете, принять с ответом 200 и проигнорировать.

  6. Проверить свежесть по timestamp.

  7. Найти заказ по id счёта. Уже оплачен — ответить 200 и ничего не делать.

  8. Сверить валюту и сумму с заказом, провести оплату, быстро ответить 2xx.

Node.js: Express и сырое тело

express.json() забирает тело и парсит его, и к моменту вызова обработчика исходных байтов уже нет. Поэтому на маршрут вебхука ставим express.raw(). Тогда req.body будет Buffer.

import express from 'express';
import crypto from 'node:crypto';

const app = express();
const API_SECRET = process.env.ZYPHER_API_SECRET.trim();

function validSignature(rawBody, received) {
  const expected = crypto.createHmac('sha256', API_SECRET).update(rawBody).digest();
  const given = Buffer.from(String(received || ''), 'hex');
  // timingSafeEqual падает на буферах разной длины, поэтому сначала длина
  return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}

app.post('/webhooks/zypher', express.raw({ type: 'application/json', limit: '256kb' }), async (req, res) => {
  if (!validSignature(req.body, req.get('X-Webhook-Signature'))) {
    return res.status(401).send('invalid signature');
  }

  const { event, data, timestamp } = JSON.parse(req.body.toString('utf8'));
  if (event !== 'invoice.paid') return res.sendStatus(200);

  try {
    await handleInvoicePaid(data, timestamp); // идемпотентно, см. ниже
    res.sendStatus(200);
  } catch (err) {
    console.error('webhook failed', err);
    res.sendStatus(500); // не-2xx: доставку повторят
  }
});

app.use(express.json()); // остальные маршруты как обычно

Если у вас не Express:

  • NestJS — NestFactory.create(AppModule, { rawBody: true }), байты лежат в req.rawBody.

  • Next.js (route handlers) — один раз await request.text(), эту же строку используйте и для HMAC, и для JSON.parse.

  • Fastify — свой content-type parser, который оставляет тело Buffer на этом маршруте.

Сравнение раскодированных из hex буферов не зависит от регистра букв в подписи. Мусор вместо hex даст буфер другой длины, и проверка длины его отсечёт.

PHP: чистый PHP, Laravel, Битрикс

Сырое тело в PHP читается из php://input. hash_hmac() по умолчанию отдаёт hex в нижнем регистре, hash_equals() сравнивает за постоянное время.

<?php
$secret   = trim(getenv('ZYPHER_API_SECRET'));
$raw      = file_get_contents('php://input');
$received = strtolower(trim($_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? ''));
$expected = hash_hmac('sha256', $raw, $secret);

if ($received === '' || !hash_equals($expected, $received)) {
    http_response_code(401);
    exit('invalid signature');
}

$payload = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);

if (($payload['event'] ?? '') !== 'invoice.paid') {
    http_response_code(200);
    exit;
}

try {
    handle_invoice_paid($payload['data'], $payload['timestamp'] ?? null); // идемпотентно
    http_response_code(200);
} catch (Throwable $e) {
    error_log('webhook failed: ' . $e->getMessage());
    http_response_code(500);
}

Где обычно спотыкаются:

  • Laravel: тело — $request->getContent(), заголовок — $request->header('X-Webhook-Signature'). Маршрут вебхука нужно исключить из CSRF-проверки, иначе запросы отсекутся до вашего кода.

  • 1С-Битрикс, WordPress и другие CMS: если стоит готовый модуль оплаты, проверку подписи он делает сам. Свой обработчик пишите только для нестандартной логики. Список готовых решений — на странице плагинов для приёма криптовалюты.

  • == и strcmp() для подписи не годятся. В hash_equals() первым аргументом идёт известное значение, вторым — пришедшее.

Python: Flask и FastAPI

В Python за постоянное время сравнивает hmac.compare_digest(). Ключ и сообщение передаются байтами.

import hashlib
import hmac
import json
import os

SECRET = os.environ["ZYPHER_API_SECRET"].strip().encode("utf-8")

def valid_signature(raw: bytes, received: str | None) -> bool:
    if not received:
        return False
    expected = hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received.strip().lower())

Flask

from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/webhooks/zypher")
def zypher_webhook():
    raw = request.get_data()  # байты, до любого парсинга
    if not valid_signature(raw, request.headers.get("X-Webhook-Signature")):
        abort(401)

    payload = json.loads(raw)
    if payload.get("event") != "invoice.paid":
        return "", 200

    handle_invoice_paid(payload["data"], payload.get("timestamp"))
    return "", 200

До get_data() не обращайтесь к request.form: чтение формы съедает поток.

FastAPI

from fastapi import FastAPI, Header, HTTPException, Request

app = FastAPI()

@app.post("/webhooks/zypher")
async def zypher_webhook(request: Request, x_webhook_signature: str | None = Header(default=None)):
    raw = await request.body()
    if not valid_signature(raw, x_webhook_signature):
        raise HTTPException(status_code=401, detail="invalid signature")

    payload = json.loads(raw)
    if payload.get("event") != "invoice.paid":
        return {"ok": True}

    await handle_invoice_paid(payload["data"], payload.get("timestamp"))
    return {"ok": True}

Параметр x_webhook_signature FastAPI сам сопоставит с заголовком X-Webhook-Signature. Pydantic-модель в качестве тела здесь лучше не объявлять: технически это работает, но провоцирует код, который доверяет полям до проверки подписи.

Почему подпись не сходится: типичные причины

Что видноПричинаЧто сделать
Не проходит ни один вебхукJSON распарсили и собрали зановоСчитать HMAC от сырых байтов
Сломалось после деплояВ секрете перевод строки или пробел из .envtrim() секрета
Не сходится только в одном языкеСекрет раскодировали из hex или base64Использовать строку секрета как есть, в UTF-8
Не сходится на части запросовMiddleware меняет кодировку или распаковывает телоЧитать сырое тело раньше остальных middleware
Не сходится за прокси или WAFТело переписывается или обрезаетсяПроверить лимиты и правила прокси
Всё работает, но дыра== или проверка за фича-флагомСравнение за постоянное время, всегда включено

Ещё две ловушки:

  • Деньги во float. Суммы вроде "100.00" приходят строками. Держите их строками или в десятичном типе: Decimal в Python, bcmath в PHP, decimal-библиотека в Node.

  • Не тот секрет. У каждого магазина свои ключ и секрет. Если магазинов несколько, берите секрет того магазина, к которому относится вебхук.

Защита от повтора: метка времени

Подписанный запрос можно перехватить (из логов, через криво настроенный прокси или отладочный сервис) и отправить ещё раз. Подпись сойдётся, тело ведь не менялось. Поле timestamp лежит внутри подписанного тела, подменить его без поломки подписи нельзя, поэтому по нему можно проверять свежесть.

const MAX_AGE_MS = 10 * 60 * 1000;

function isFresh(ts) {
  if (typeof ts !== 'number') return false;
  const ms = ts < 1e12 ? ts * 1000 : ts; // секунды или миллисекунды
  return Math.abs(Date.now() - ms) <= MAX_AGE_MS;
}

Что делать с устаревшей меткой, решаете вы. Просто отклонять — значит рискнуть настоящим платежом, если на сервере уплыли часы или повтор пришёл с большой задержкой. Надёжнее так: устаревшему телу не верить, а запросить счёт через API и действовать по его ответу.

async function fetchInvoice(invoiceId) {
  const sign = crypto.createHmac('sha256', API_SECRET).update('').digest('hex'); // для GET — пустая строка
  const res = await fetch(`https://zypher.exchange/api/v1/invoice/${encodeURIComponent(invoiceId)}`, {
    headers: { 'X-API-Key': process.env.ZYPHER_API_KEY, 'X-API-Sign': sign },
  });
  if (!res.ok) throw new Error(`invoice lookup failed: ${res.status}`);
  return res.json(); // формат ответа: см. /docs
}

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

Идемпотентность по id счёта и повторные доставки

Если ваш сервер лежит, не успел ответить или вернул ошибку, Zypher повторяет доставку, всего до 5 попыток. Бывает и наоборот: вы ответили, а ответ потерялся в сети, и событие пришло дважды. Обработать оплату ровно один раз — задача вашей стороны.

Надёжно это делается ограничением в базе, а не проверкой в памяти:

CREATE TABLE processed_webhooks (
  invoice_id   TEXT PRIMARY KEY,
  processed_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);
async function handleInvoicePaid(data, timestamp) {
  const invoice = isFresh(timestamp) ? data : await fetchInvoice(data.invoiceId);
  if (!['PAID', 'OVERPAID'].includes(invoice.status)) return;

  await db.transaction(async (tx) => {
    const inserted = await tx.query(
      'INSERT INTO processed_webhooks (invoice_id) VALUES ($1) ON CONFLICT DO NOTHING RETURNING invoice_id',
      [data.invoiceId],
    );
    if (inserted.rowCount === 0) return; // уже обработан: ничего не делаем, но отвечаем 200

    const order = await tx.orders.findByInvoiceId(data.invoiceId);
    if (!order || order.currency !== invoice.currency) throw new Error('order mismatch');
    await tx.orders.markPaid(order.id, { status: invoice.status });
  });
  // письма, ключи и доступы — после коммита, через очередь
}

Правила, которые экономят нервы:

  1. Сохраняйте id счёта при создании. Его возвращает POST /api/v1/invoice. Ищите заказ по нему, а не по номеру заказа из тела вебхука.

  2. Отвечайте 2xx быстро. Запись в базу — и сразу ответ. Письма, выдачу доступа и сообщения в Telegram отправляйте из очереди. Точный лимит времени указан в документации.

  3. На дубликат отвечайте 200. Это не ошибка. Ответ 4xx или 5xx только вызовет новые повторы.

  4. На свою поломку отвечайте 5xx. Если упала база, следующая попытка пройдёт.

  5. OVERPAID обрабатывайте явно. Заказ выполняется, а разницу вы либо возвращаете, либо зачисляете клиенту на баланс.

Как проверить обработчик до боевого платежа

Подпишите тестовое тело сами и отправьте его на локальный сервер:

BODY='{"event":"invoice.paid","data":{"invoiceId":"test-1","status":"PAID","currency":"USDT","amount":"10.00"},"timestamp":'$(date +%s000)'}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$ZYPHER_API_SECRET" | awk '{print $NF}')

curl -i -X POST http://localhost:3000/webhooks/zypher \
  -H 'Content-Type: application/json' \
  -H "X-Webhook-Signature: $SIG" \
  -H 'X-Webhook-Event: invoice.paid' \
  --data-binary "$BODY"

Прогоните три варианта: как есть (ждём 200), с изменённым после подписи символом в теле (ждём 401) и ещё раз без изменений (ждём 200 без повторной выдачи товара). Используйте --data-binary, а не -d, чтобы curl отправил байты без изменений. После этого оплатите один небольшой настоящий счёт. URL вебхука должен быть доступен из интернета, поэтому для локальной машины нужен туннель или тестовый сервер.

Чек-лист перед запуском:

  • HMAC считается от сырого тела, JSON разбирается после проверки

  • Сравнение за постоянное время, запрос без заголовка отклоняется

  • Секрет без пробелов, свой для каждого магазина, не лежит в репозитории

  • Незнакомые события получают 200 и игнорируются

  • Уникальный индекс по id счёта

  • Подозрительные запросы перепроверяются через GET /api/v1/invoice/:id

  • Медленные действия вынесены в очередь

Как устроены счета, адреса и уведомления целиком, описано на странице криптоэквайринга Zypher, а сторона создания счёта разобрана в пошаговой инструкции по приёму USDT на сайте. Ключ и секрет API появятся сразу после того, как вы создадите магазин.

Частые вопросы

Почему подпись вебхука никогда не совпадает?

Чаще всего тело распарсили и собрали обратно до подсчёта HMAC, и байты разошлись с подписанными. Вторая по частоте причина — перевод строки или пробел в секрете, прочитанном из файла окружения. Считайте HMAC от сырых байтов и обрежьте секрет, и подписи сойдутся.

Обычное сравнение строк правда опасно?

Обычный == останавливается на первом несовпавшем символе, и по времени ответа можно судить, какая часть подобранной подписи верна. По сети эффект слабый, но достаточно реальный, чтобы во всех популярных языках была функция сравнения за постоянное время. crypto.timingSafeEqual, hash_equals и hmac.compare_digest занимают одну строку.

Как не провести один платёж дважды?

Сделайте уникальный ключ по id счёта и вставляйте строку в той же транзакции, где заказ помечается оплаченным. Если вставка упёрлась в конфликт, событие уже обработано: отвечайте 200 и ничего не делайте. Это закрывает и повторные доставки, и сетевые дубли, и повтор перехваченного запроса.

Что будет, если сервер лежал в момент отправки вебхука?

Доставку повторят, всего до 5 попыток. Если все они не прошли, статус счёта всё равно можно получить через GET /api/v1/invoice/:id. Периодическая задача, которая перепроверяет недавние неоплаченные заказы через API, — хорошая страховка.

Отклонять ли вебхуки со старой меткой времени?

Отказ по старой метке отсекает простой повтор, но жёсткое окно может потерять настоящий платёж, если на сервере сбились часы. Надёжнее считать такой вебхук сигналом: телу не верить, а запросить счёт через API и действовать по ответу. Основной защитой в любом случае остаётся идемпотентность по id счёта.

Можно ли проверять IP вместо подписи?

Проверка IP может быть дополнительным слоем, но она ломается при смене инфраструктуры и ничего не говорит о целостности тела. Подпись HMAC подтверждает и отправителя, и содержимое. Подпись обязательна, всё остальное — по желанию.