Подписи webhook-событий
Каждый webhook-запрос сопровождается заголовком X-FlowWorker-Signature в формате:
t=<unix_seconds>,v1=<hex_hmac_sha256>v1 - это HMAC-SHA256, где:
- Ключ: ваш секрет подписки (то, что показал UI один раз при создании).
- Сообщение: строка
{t}.{raw_body}, где{t}- то жеt=из заголовка,{raw_body}- необработанное тело запроса (важно: до парсинга/нормализации JSON).
Алгоритм проверки
Заголовок раздела «Алгоритм проверки»- Прочитайте
X-FlowWorker-Signature, распарситеtиv1. - Прочитайте сырое тело запроса (до JSON-парсинга).
- Вычислите
expected = HMAC_SHA256(secret, f"{t}.{raw_body}")в hex. - Сравните
expectedсv1в constant-time (не оператором==). - Проверьте что
|now - t| < 300секунд (защита от replay).
Node.js (Express)
Заголовок раздела «Node.js (Express)»import crypto from 'node:crypto';import express from 'express';
const app = express();const SECRET = process.env.WEBHOOK_SECRET;
// Важно: получаем raw body, не parsed JSONapp.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => { const sig = req.header('X-FlowWorker-Signature') || ''; const [tPart, v1Part] = sig.split(','); const t = parseInt(tPart.split('=')[1], 10); const v1 = v1Part.split('=')[1];
if (Math.abs(Date.now() / 1000 - t) > 300) { return res.status(400).send('stale'); }
const expected = crypto .createHmac('sha256', SECRET) .update(`${t}.${req.body.toString('utf8')}`) .digest('hex');
const a = Buffer.from(expected, 'utf8'); const b = Buffer.from(v1, 'utf8'); if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) { return res.status(401).send('bad signature'); }
// OK - обрабатываем const event = JSON.parse(req.body); console.log(event.type, event.data); res.status(200).end();});
app.listen(3000);Python (Flask)
Заголовок раздела «Python (Flask)»import hmac, hashlib, os, timefrom flask import Flask, request, abort
app = Flask(__name__)SECRET = os.environ['WEBHOOK_SECRET'].encode('utf-8')
@app.post('/webhook')def webhook(): sig = request.headers.get('X-FlowWorker-Signature', '') parts = dict(p.split('=', 1) for p in sig.split(',')) t = int(parts.get('t', '0')) v1 = parts.get('v1', '')
if abs(int(time.time()) - t) > 300: abort(400, 'stale')
raw = request.get_data() expected = hmac.new(SECRET, f'{t}.{raw.decode("utf-8")}'.encode('utf-8'), hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, v1): abort(401, 'bad signature')
event = request.get_json(force=True) print(event['type'], event['data']) return '', 200<?php$secret = getenv('WEBHOOK_SECRET');$rawBody = file_get_contents('php://input');$sig = $_SERVER['HTTP_X_FLOWWORKER_SIGNATURE'] ?? '';
$parts = [];foreach (explode(',', $sig) as $p) { [$k, $v] = array_pad(explode('=', $p, 2), 2, ''); $parts[$k] = $v;}$t = (int)($parts['t'] ?? 0);$v1 = $parts['v1'] ?? '';
if (abs(time() - $t) > 300) { http_response_code(400); exit('stale');}
$expected = hash_hmac('sha256', "{$t}.{$rawBody}", $secret);
if (!hash_equals($expected, $v1)) { http_response_code(401); exit('bad signature');}
$event = json_decode($rawBody, true);error_log("{$event['type']}: " . json_encode($event['data']));http_response_code(200);curl (тестовая проверка от руки)
Заголовок раздела «curl (тестовая проверка от руки)»Если хотите проверить подпись вручную для отладки:
TIMESTAMP=1747234567BODY='{"id":"abc","type":"task.created",...}'SECRET='your-webhook-secret'echo -n "${TIMESTAMP}.${BODY}" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}'Результат должен совпасть с v1= из заголовка.
Частые ошибки
Заголовок раздела «Частые ошибки»- Парсить JSON до проверки. Любая нормализация (переупорядочивание ключей, удаление пробелов) сломает подпись. Сохраняйте оригинальный body bytes.
- Сравнивать оператором
==. Уязвимо к timing-атакам. Используйтеcrypto.timingSafeEqual/hmac.compare_digest. - Не проверять
t. Без защиты от replay злоумышленник может пересылать перехваченный валидный запрос неограниченно долго.