🔔 Webhooks
Что это. Вебхук — обмен событиями по HTTP без опроса: одна сторона отправляет запрос сразу, как только что-то произошло, вторая его принимает и обрабатывает.
Когда нужно. Когда внешняя система должна узнавать об изменениях в Fixorix в момент их появления, а не выяснять их регулярными запросами к API. И наоборот — когда события внешней системы должны попадать внутрь платформы.
Механизм вебхуков в Fixorix реализован для обоих направлений: приём событий извне и доставка событий наружу — с HMAC-подписью, повторными попытками и журналом доставок.
Но пользоваться им пока нельзя: настраиваться вебхуки будут в дашборде, а раздела вебхуков там ещё нет, и доставка событий в исходящие вебхуки ещё не запущена. Каталога типов событий продукта тоже пока нет. Запускать сценарии из внешней системы уже можно — через вебхук-триггер сценария.
Два направления
Направления независимы: у каждого своя настройка, свои ограничения и свои коды ответа.
| Направление | Кто кому отправляет | Для чего | Страница |
|---|---|---|---|
| Исходящие | Fixorix → ваш сервер | Получать события платформы на свой адрес | Исходящие вебхуки |
| Входящие | Ваша система → Fixorix | Передавать в платформу события извне | Входящие вебхуки |
Что уже есть и чего ещё нет
| Возможность | Состояние |
|---|---|
| Приём событий по секретной ссылке | Реализован: ссылки приёма — на доменах webhook.fixorix.ru и webhook-world.fixorix.ru. Завести точку приёма из интерфейса пока нельзя |
| Проверка секрета и challenge-рукопожатие на приёме | Реализованы |
| Доставка событий на HTTPS-адрес с подписью HMAC-SHA256 | Реализована, но события в исходящие вебхуки ещё не доставляются |
| Повторные попытки, пауза, ротация секрета, тестовая отправка | Реализованы |
| Журнал доставок и журнал HTTP-попыток | Реализованы |
| Каталог типов событий продукта | Пока нет — тип события задаёт та система, которая его публикует |
| Доставка событий Fixorix в исходящие вебхуки | Пока не запущена |
| Раздел «Вебхуки» в интерфейсе | Пока нет |
Механизм реализован, но подписаться на события Fixorix пока нельзя: настроить исходящие вебхуки из интерфейса нельзя, каталога типов событий нет, а доставка событий в исходящие вебхуки ещё не запущена.
Страницы раздела
| Страница | О чём |
|---|---|
| Исходящие вебхуки | Подписка, формат доставки, заголовки, подпись, повторные попытки, журнал |
| Входящие вебхуки | Точка приёма, секретная ссылка, проверка секрета, challenge, коды ответа |
| Типы событий | Что такое тип события, конверт события, ограничения формата |
| Вебхуки на дашборде | Как раздел будет выглядеть в интерфейсе, когда появится |
Что делать сейчас
Пока доставка событий в исходящие вебхуки не запущена, задачи, ради которых обычно берут вебхуки, решаются тремя способами.
Опрос REST API
Актуальные данные можно получать запросами: REST API даёт доступ к ботам и каналам, участникам, сообщениям, базе знаний, сценариям и их запускам, обращениям техподдержки, тегам, метрикам и другим разделам — полный список в Swagger UI. Учитывайте лимит — 1000 запросов в минуту на каждый API-ключ.
Вебхук-триггер сценария
Обратное направление работает: у сценария есть тип триггера «Webhook» — внешний вызов запускает сценарий. Подсказка в редакторе: «URL вебхука для этого flow будет доступен после публикации». Тело запроса — не больше 64 КиБ, на проект — не больше 600 вебхуков в минуту.
Готового URL в интерфейсе нет: после публикации он нигде не показывается. Адрес собирается вручную — возьмите flowId из адреса страницы редактора (/project/{projectId}/flows/{flowId}/editor) и вызовите метод Public API, описанный ниже.
Вебхук-триггер сценария вызывается либо с токеном пользователя, у которого в проекте роль «Администратор» или «Владелец», либо через Public API по API-ключу с правом FLOWS_WRITE.
Внешняя система запускает сценарий через Public API: POST https://api.fixorix.ru/v1/flow/triggers/{flowId}/webhook с заголовком Authorization: Bearer <API-ключ>. Ключу нужно право FLOWS_WRITE. Тело — {"payload": {...}, "headers": {...}, "userId": "...", "scopeId": "..."}, все поля необязательны; ключи authorization, cookie, set-cookie, proxy-authorization, x-api-key из поля headers в сценарий не попадают. Ответ — 202 с созданным запуском.
Ошибки: 404 — сценарий не найден, 409 ILLEGAL_STATE — сценарий не опубликован, 400 TRIGGER_TYPE_MISMATCH — у сценария другой триггер, 400 INPUT_VALIDATION_FAILED — значения не подходят под входные переменные, 422 GUARDRAIL_VIOLATION — payload больше 64 КиБ, 429 RATE_LIMIT_EXCEEDED — больше 600 вызовов в минуту на проект.
Сценарий с триггером «Ручной запуск» запускается методом POST /v1/flow/executions/start (право FLOWS_MANAGE).
Подробнее о методах — на странице Сценарии в API.
Подробнее — в разделе Триггеры.
Реакции внутри платформы
Многое из того, ради чего обычно нужен внешний сервер, делается без него — Сценариями: автоответы, смена статуса, уведомления сотрудникам, HTTP-запрос в вашу систему прямо из сценария, обращение к AI.
Ограничения
- Каталога типов событий продукта нет: тип события — произвольная строка, её задаёт публикующая сторона.
- Доставка событий Fixorix в исходящие вебхуки ещё не запущена.
- Завести подписку или точку приёма самостоятельно пока нельзя. Раздела вебхуков в интерфейсе нет: вебхуки в дашборде встречаются только в связи с вебхук-триггером сценария (тип триггера, переменные «Payload вебхука» и «Заголовки вебхука», событие «Сценарий … запущен по вебхуку» в чате).
→ Исходящие вебхуки · Входящие вебхуки · Типы событий · Вебхуки на дашборде · REST API