Безопасность webhooks
import { Tabs, TabItem } from ‘@astrojs/starlight/components’;
Адрес получателя
Заголовок раздела «Адрес получателя»Для вебхуков требуется общедоступный HTTPS-адрес без имени пользователя и пароля в URL. При каждом новом соединении FlowWorker проверяет все IP-адреса, полученные из DNS, и подключается только к проверенному адресу. Если хотя бы один из адресов относится к частной сети, loopback, link-local или другому служебному диапазону, доставка завершается ошибкой. Перенаправления не выполняются, HTTP 3xx считается ошибкой доставки.
Управлять вебхуками могут владелец и администраторы, которые уже вступили в аккаунт.
Подпись запроса
Заголовок раздела «Подпись запроса»Каждый webhook-запрос подписывается HMAC-SHA256 с вашим секретом. Подробный алгоритм проверки одиночной подписи описан в Подписях webhook-событий.
Ротация секретов
Заголовок раздела «Ротация секретов»Webhook secret можно ротировать без даунтайма приёмника. После POST /api/v1/accounts/{accountId}/webhooks/{id}/rotate-secret:
- Новый секрет доступен сразу (показывается один раз в ответе).
- Старый секрет продолжает подписывать параллельно ещё 24 часа.
- Заголовок
X-FlowWorker-Signatureсодержит обе подписи:t=<unix>,v1=<новая>,v1=<старая>. - Приёмник должен проверить любую
v1=- если хотя бы одна совпадает, запрос валиден. - После 24 часов старый секрет удаляется автоматически; заголовок снова содержит одну подпись.
Рекомендуемый порядок ротации
Заголовок раздела «Рекомендуемый порядок ротации»- Вызовите
/rotate-secretи сохраните новый секрет. - Обновите
WEBHOOK_SECRETв вашем приёмнике. - Подождите окончания 24-часового окна - старые доставки продолжат проходить проверку.
Проверка нескольких подписей
Заголовок раздела «Проверка нескольких подписей»Во время переходного периода заголовок выглядит так:
X-FlowWorker-Signature: t=1747234567,v1=aabbcc...,v1=ddeeff...Ваш приёмник должен проверять каждую v1= и принимать запрос, если хотя бы одна совпадает.
function verify(body, header, secret) {
const parts = header.split(’,’);
const tPart = parts.find((p) => p.startsWith(‘t=’));
if (!tPart) return false;
const timestamp = tPart.slice(2);
const signedPayload = ${timestamp}.${body};
const expected = createHmac(‘sha256’, secret).update(signedPayload).digest(‘hex’);
// any v1=… matching is enough for (const part of parts) { if (!part.startsWith(‘v1=’)) continue; const sig = part.slice(3); if (sig.length === expected.length && timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) { return true; } } return false; }
</TabItem><TabItem label="Python">```pythonimport hmac, hashlib
def verify(body: str, header: str, secret: str) -> bool: parts = header.split(',') t = next((p[2:] for p in parts if p.startswith('t=')), None) if not t: return False signed_payload = f"{t}.{body}" expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest() for p in parts: if not p.startswith('v1='): continue if hmac.compare_digest(p[3:], expected): return True return FalseВажно: всегда используйте constant-time сравнение (
timingSafeEqual/hmac.compare_digest/hash_equals) - оператор==уязвим к timing-атакам.