Вебхуки
Страница для администраторов. Вебхуки — это два независимых канала событий: входящие (внешняя система стучится в TAktom) и исходящие (TAktom сообщает наружу). Настраиваются они в разных разделах и не связаны между собой.
| Направление | Раздел | Кто кому шлёт |
|---|---|---|
| Входящие | Админ → Вебхуки | Внешняя система → TAktom |
| Исходящие | Админ → Внешние вызовы | TAktom → внешняя система |
Входящие вебхуки
Админ → Вебхуки выдаёт внешней системе секретный адрес. Всё, что на него приходит, проверяется, записывается в журнал и превращается во внутреннее событие — на него подписываются правила автоматизации и функции продукта.
Приём и обработка — разные вещи
Эта страница отвечает только за приём: кого впускаем, как проверяем, что пришло. Что делать с событием — завести задачу, дописать комментарий, позвать другое правило — решает правило автоматизации. Поэтому один заведённый хук обслуживает сколько угодно сценариев: правил на него можно навесить несколько.
Как завести хук
Кнопка «Добавить хук» открывает форму:
| Поле | Что задаёт |
|---|---|
| Имя | Строчные латинские буквы, цифры и дефис. Имя становится частью имени события (taskflow.hook.<имя>), на которое ссылаются правила, и потом не меняется. |
| Название | Человекочитаемая подпись в списке. Необязательно. |
| Проверка отправителя | Как убедиться, что запрос пришёл от того, кому вы дали адрес, — см. ниже. |
| Общий секрет | Появляется для двух режимов проверки из трёх. Тот же секрет вводится на стороне отправителя. |
| Заголовок подписи | Только для проверки подписью: в каком заголовке отправитель передаёт подпись (x-hub-signature-256 у GitHub). |
| Заголовок идентификатора доставки | Если отправитель нумерует доставки (x-github-delivery), повтор той же доставки не создаст второго события. Пусто — защиты от дублей нет. |
После создания на экране появляется готовый адрес вида https://<ваш-хост>/hooks/<токен>. Его и вставляют в настройки внешней системы.
Адрес показывается один раз
В базе хранится только его отпечаток, поэтому «подсмотреть потом» нельзя. Скопируйте адрес сразу; закрыв карточку, вы его больше не увидите. Потеряли — не восстанавливайте, а нажмите «Перевыпустить»: старый адрес перестаёт работать немедленно, новый нужно вписать отправителю.
Проверка отправителя
Секретный адрес сам по себе — уже пропуск, но не для всех сценариев его хватает. Режимов три:
| Режим | Когда выбирать | Что защищает |
|---|---|---|
| Только токен в адресе | Отправитель умеет лишь «сделать POST на адрес»: Slack, n8n, Jira Automation | Адрес, но не содержимое: тот, кто узнал адрес, пришлёт что угодно. |
| Подпись тела (HMAC-SHA256) | GitHub, Stripe, Shopify и все, кто подписывает тело | Единственный режим, где тело нельзя подменить по дороге. |
| Заголовок Bearer | Отправитель подписывать не умеет, но заголовок поставить может (GitLab) | Секрет в заголовке; тело не подписано. |
Выбирайте подпись везде, где отправитель её поддерживает. Хук, которому нужен секрет, но секрет не задан, помечен в списке предупреждением — такой хук впускать никого не должен.
Список хуков
Таблица показывает по каждому хуку: название и имя, режим проверки, имя события, которое он порождает, время последнего вызова и состояние. Действия:
- Перевыпустить — новый адрес, старый умирает сразу.
- Выключить / Включить — приём останавливается, настройки сохраняются. Выключенный хук отвечает отправителю отказом, а не тишиной.
- Удалить — хук исчезает, журнал его вызовов остаётся: история приёма не переписывается.
Хук, заведённый не вами, а функцией продукта, помечен её именем. Такой хук работает, только пока включена сама функция.
Журнал вызовов
Нижний блок страницы — журнал: время, хук, ответ отправителю, код результата, размер тела и адрес источника. Фильтры — по хуку, по результату (принятые / отклонённые) и размер страницы. Записываются и отклонённые попытки — иначе «вебхук не приходит» выглядело бы полной тишиной.
Кнопка «Показать» раскрывает заголовки и тело запроса — то, ради чего журнал в первую очередь и нужен: без реального тела правило не написать. Заголовки с секретами (Authorization, заголовок подписи) из журнала вырезаны. Глубина журнала — 14 дней.
Коды результата читаются напрямую:
| Код | Что произошло |
|---|---|
HOOK_ACCEPTED | Принято, событие создано. |
HOOK_UNKNOWN_TOKEN | Адрес не соответствует ни одному хуку: опечатка или перевыпущенный токен. |
HOOK_DISABLED | Хук выключен — или выключена функция, которой он принадлежит. |
HOOK_BAD_SIGNATURE | Подпись или Bearer не сошлись: разные секреты на двух сторонах. |
HOOK_BODY_TOO_LARGE | Тело превысило допустимый размер. |
HOOK_DUPLICATE | Повторная доставка с тем же идентификатором — второе событие не создавалось. |
От приёма до действия
- Заведите хук и вставьте выданный адрес в настройки внешней системы.
- Пусть она пришлёт настоящее событие, и посмотрите его тело в журнале.
- Создайте правило автоматизации с триггером-событием этого хука и условиями по полям тела.
- Проверьте правило сухим прогоном, а потом включите.
Отправитель получил 200 — а ничего не произошло
Это нормальное разделение ответственности: приём удался, значит дальше дело в правиле. Смотрите журнал прогонов автоматизации, а не журнал вызовов. И наоборот: если в журнале вызовов записи нет вовсе, запрос до инстанса не дошёл — проверяйте адрес и сеть на стороне отправителя.
Хуки, которые заводят сами функции
Некоторым функциям входящий вебхук нужен для работы, и они заводят его сами — такой хук виден в общем списке с пометкой владельца:
- Dev-ссылки — принимают push-события GitHub, GitLab и Bitbucket, чтобы показывать ветки и коммиты на карточке задачи. Хук заводит администратор, а адрес вставляет в настройки репозитория; см. Связь задач с git-хостингом.
- Почта через JMAP — принимает уведомление почтового узла о новом письме; см. Почта → Приём писем.
Такие хуки не удаляйте вручную: функция заведёт их заново, а внешней системе придётся выдавать новый адрес.
Исходящие вебхуки
Админ → Внешние вызовы — обратное направление: TAktom сам делает POST во внешнюю систему, когда что-то происходит.
У каждого вызова задаются:
| Поле | Что задаёт |
|---|---|
| Название | Подпись в списке — например, «Slack уведомления». |
| URL | Куда отправлять. |
| Secret | Общий секрет для подписи тела (HMAC-SHA256), чтобы принимающая сторона убедилась в отправителе. Пустое поле при редактировании означает «не менять». |
| События | Через запятую: на какие события реагировать. Хотя бы одно. |
| Активен | Рубильник, не удаляющий настройку. |
Кнопка «Тест» отправляет пробный запрос и сразу показывает результат; ссылка «Доставки» открывает журнал по конкретному вызову — событие, время и исход. Вызвать внешний адрес может и действие правила автоматизации.
Внутренние адреса заблокированы
Запросы на адреса внутренней сети (localhost, приватные диапазоны, служебные адреса облака) отклоняются. Это защита от использования вебхука как средства разведки вашей инфраструктуры, и обойти её настройкой нельзя.
Что дальше
- Автоматизация — правила, которые обрабатывают принятые события.
- Плагины — включение функций, о которых говорится выше.
- ИИ и доступ по API — другие способы связать TAktom с внешними системами.
Смотрите также
- Почта → Приём писем — приём писем работает через такой же входящий хук.
- ИИ и доступ по API → Связь задач с git-хостингом — готовый сценарий на входящем вебхуке, по шагам.
- Функции и настройки → Автоматизация, вебхуки и уведомления — место обоих направлений в общей картине инстанса.
- Конфигурация → Обязательные параметры —
APP_BASE_URL, из которого складывается адрес хука.