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

Webhooks - быстрый старт

  1. Подготовьте endpoint на вашей стороне, готовый принять POST с JSON-телом и заголовком X-FlowWorker-Signature. Для теста можно использовать https://webhook.site или локальный ngrok-туннель.

  2. Создайте подписку. В UI: Настройки команды → Webhooks → Создать webhook. Укажите URL, типы событий (task.created, task.updated, task.deleted, project.created), скопируйте показанный секрет - он показывается один раз.

  3. Спровоцируйте событие. Создайте задачу через 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/tasks
  4. Получите HTTP POST. На ваш endpoint придёт запрос:

    POST /your/path
    Content-Type: application/json
    User-Agent: FlowWorker-Webhooks/1.0
    X-FlowWorker-Event: task.created
    X-FlowWorker-Delivery: 12345
    X-FlowWorker-Subscription: 7
    X-FlowWorker-Timestamp: 1747234567
    X-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
    }
    }
  5. Проверьте подпись. См. Подписи webhook-событий. Это критически важно - без проверки любой может подделать запрос.

  6. Верните 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}/resume

resume сбрасывает счётчик dead-letter’ов и снимает паузу.

Ответ обоих эндпоинтов - обновлённый объект WebhookSubscription. Дополнительные поля:

ПолеТипОписание
pausedAtISO-8601 | nullМомент приостановки. null если подписка активна.
pausedReason"manual" | "auto-dead-letter" | nullПричина паузы: manual - поставлена вручную; auto-dead-letter - автоматически после 50 подряд dead-letter’ов.

При retry один и тот же id (поле в payload) приходит несколько раз с разными X-FlowWorker-Delivery. Дедуплицируйте по id на вашей стороне.