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

Безопасность 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 часов старый секрет удаляется автоматически; заголовок снова содержит одну подпись.
  1. Вызовите /rotate-secret и сохраните новый секрет.
  2. Обновите WEBHOOK_SECRET в вашем приёмнике.
  3. Подождите окончания 24-часового окна - старые доставки продолжат проходить проверку.

Во время переходного периода заголовок выглядит так:

X-FlowWorker-Signature: t=1747234567,v1=aabbcc...,v1=ddeeff...

Ваш приёмник должен проверять каждую v1= и принимать запрос, если хотя бы одна совпадает.

```js import { createHmac, timingSafeEqual } from 'node:crypto';

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">
```python
import 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
```php function verify(string $body, string $header, string $secret): bool { $parts = explode(',', $header); $timestamp = null; foreach ($parts as $p) { if (str_starts_with($p, 't=')) { $timestamp = substr($p, 2); break; } } if (!$timestamp) return false; $signedPayload = "{$timestamp}.{$body}"; $expected = hash_hmac('sha256', $signedPayload, $secret); foreach ($parts as $p) { if (!str_starts_with($p, 'v1=')) continue; if (hash_equals(substr($p, 3), $expected)) return true; } return false; } ```

Важно: всегда используйте constant-time сравнение (timingSafeEqual / hmac.compare_digest / hash_equals) - оператор == уязвим к timing-атакам.