Перейти к содержимому

Подписи webhook-событий

Каждый webhook-запрос сопровождается заголовком X-FlowWorker-Signature в формате:

t=<unix_seconds>,v1=<hex_hmac_sha256>

v1 - это HMAC-SHA256, где:

  • Ключ: ваш секрет подписки (то, что показал UI один раз при создании).
  • Сообщение: строка {t}.{raw_body}, где {t} - то же t= из заголовка, {raw_body} - необработанное тело запроса (важно: до парсинга/нормализации JSON).
  1. Прочитайте X-FlowWorker-Signature, распарсите t и v1.
  2. Прочитайте сырое тело запроса (до JSON-парсинга).
  3. Вычислите expected = HMAC_SHA256(secret, f"{t}.{raw_body}") в hex.
  4. Сравните expected с v1 в constant-time (не оператором ==).
  5. Проверьте что |now - t| < 300 секунд (защита от replay).
import crypto from 'node:crypto';
import express from 'express';
const app = express();
const SECRET = process.env.WEBHOOK_SECRET;
// Важно: получаем raw body, не parsed JSON
app.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);
import hmac, hashlib, os, time
from 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);

Если хотите проверить подпись вручную для отладки:

Окно терминала
TIMESTAMP=1747234567
BODY='{"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 злоумышленник может пересылать перехваченный валидный запрос неограниченно долго.