Webhooks - быстрый старт
-
Подготовьте endpoint на вашей стороне, готовый принять
POSTс JSON-телом и заголовкомX-FlowWorker-Signature. Для теста можно использоватьhttps://webhook.siteили локальный ngrok-туннель. -
Создайте подписку. В UI:
Настройки команды → Webhooks → Создать webhook. Укажите URL, типы событий (task.created,task.updated,task.deleted,project.created), скопируйте показанный секрет - он показывается один раз. -
Спровоцируйте событие. Создайте задачу через API:
Окно терминала curl -X POST \-H "Authorization: Bearer fw_live_xxx" \-H "Content-Type: application/json" \-d '{"projectId":123,"title":"Webhook test"}' \https://api.flowworker.ru/api/public/v1/tasksawait fetch('https://api.flowworker.ru/api/public/v1/tasks', {method: 'POST',headers: {Authorization: `Bearer ${process.env.FW_KEY}`,'Content-Type': 'application/json'},body: JSON.stringify({ projectId: 123, title: 'Webhook test' })});requests.post('https://api.flowworker.ru/api/public/v1/tasks',headers={'Authorization': f'Bearer {os.environ["FW_KEY"]}'},json={'projectId': 123, 'title': 'Webhook test'})<?php$ch = curl_init('https://api.flowworker.ru/api/public/v1/tasks');curl_setopt_array($ch, [CURLOPT_POST => true,CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('FW_KEY'),'Content-Type: application/json',],CURLOPT_POSTFIELDS => json_encode(['projectId' => 123,'title' => 'Webhook test',]),CURLOPT_RETURNTRANSFER => true,]);curl_exec($ch);curl_close($ch); -
Получите HTTP POST. На ваш endpoint придёт запрос:
POST /your/pathContent-Type: application/jsonUser-Agent: FlowWorker-Webhooks/1.0X-FlowWorker-Event: task.createdX-FlowWorker-Delivery: 12345X-FlowWorker-Subscription: 7X-FlowWorker-Timestamp: 1747234567X-FlowWorker-Signature: t=1747234567,v1=abc...hexhash...{"id": "9c2d8f1e5a4b7c6d3e0f1a2b3c4d5e6f","type": "task.created","createdAt": "2026-05-16T10:42:18Z","accountId": 42,"data": {"id": 9001,"projectId": 123,"title": "Webhook test","status": "todo","createdAt": "2026-05-16T10:42:18Z","version": 1}} -
Проверьте подпись. См. Подписи webhook-событий. Это критически важно - без проверки любой может подделать запрос.
-
Верните
2xx. В пределах 10 секунд. Иначе FlowWorker повторит доставку с экспоненциальным backoff (см. Retry и dead-letter).
Фильтр по проектам
Заголовок раздела «Фильтр по проектам»При создании subscription можно указать projectIds - массив project ID. Подписчик получит только события из этих проектов. Пустой массив (или отсутствие поля) означает все проекты аккаунта (поведение по умолчанию).
POST /api/v1/accounts/5/webhooks{ "url": "https://your-app.io/hook", "eventTypes": ["task.commented", "task.completed"], "projectIds": [12, 13]}Если projectIds не указан или равен [] - subscription получает события всех проектов аккаунта (back-compat).
Управление подпиской
Заголовок раздела «Управление подпиской»Пауза и возобновление
Заголовок раздела «Пауза и возобновление»Доставку событий можно временно приостановить без удаления подписки.
Приостановить:
POST /api/v1/accounts/{accountId}/webhooks/{id}/pauseВозобновить:
POST /api/v1/accounts/{accountId}/webhooks/{id}/resumeresume сбрасывает счётчик dead-letter’ов и снимает паузу.
Ответ обоих эндпоинтов - обновлённый объект WebhookSubscription. Дополнительные поля:
| Поле | Тип | Описание |
|---|---|---|
pausedAt | ISO-8601 | null | Момент приостановки. null если подписка активна. |
pausedReason | "manual" | "auto-dead-letter" | null | Причина паузы: manual - поставлена вручную; auto-dead-letter - автоматически после 50 подряд dead-letter’ов. |
Дедупликация
Заголовок раздела «Дедупликация»При retry один и тот же id (поле в payload) приходит несколько раз с разными X-FlowWorker-Delivery. Дедуплицируйте по id на вашей стороне.