Вебхуки

Вебхук — точка входа для событий из ваших систем. Мониторинг, CI, ATS, биллинг, форма на сайте — любая система, умеющая отправить HTTP-запрос, может разбудить агента в Баунс.

Вебхук не существует сам по себе: он живёт на автопилоте как один из его триггеров. Автопилот отвечает за то, что произойдёт (кому уйдёт работа и с каким поручением), вебхук — за то, когда.

Настройка

1. Откройте Автопилот и создайте автопилот: название, исполнитель — агент, команда или воркфлоу — и промпт с текстом поручения.
2. Нажмите Добавить триггер, выберите тип Вебхук, сохраните. Адрес генерируется при сохранении.
3. Скопируйте URL вебхука кнопкой на строке триггера.
4. Настройте свою систему на отправку POST по этому адресу.

curl -X POST "$URL_ВЕБХУКА" \
  -H "Content-Type: application/json" \
  -d '{"event":"deploy.finished","status":"failed","service":"billing"}'

Тело может быть любым: JSON разбирается и показывается агенту структурно, остальные форматы передаются как есть.

Что получает исполнитель

Это и есть главный приём: агенту не нужно ходить в вашу систему за подробностями — событие приносит их с собой, а инструкции о том, что с ними делать, лежат в промпте автопилота и скиллах агента.

Что отвечает Баунс

Ответ приходит сразу, ещё до того как агент начнёт работу: приём события и его обработка разведены.

202 на повтор и на выключенный автопилот — намеренное решение: отправляющая система не должна уходить в шторм ретраев из-за того, что на нашей стороне что-то временно выключено.

Статусы доставки

Каждый входящий запрос записывается как доставка с одним из статусов:

Повторы и дедупликация

Доставки идемпотентны. Ключ считается по телу запроса, и повтор с тем же ключом не создаёт вторую задачу. Практический вывод: ретраи вашей системы безопасны, и включать у себя «доставку ровно один раз» не требуется.

Адрес — это ключ доступа

Вебхук не подписывается. Единственный ключ доступа — сам адрес: кто знает URL, тот может запустить автопилот.

Журнал доставок

У каждого автопилота есть список доставок, и это основной инструмент отладки интеграции. По каждой видно: время, статус, ключ дедупликации, число попыток, код ответа, а также сырое тело запроса и заголовки.

Любую доставку можно повторить вручную — удобно, когда вы настраиваете обработку и не хотите каждый раз просить внешнюю систему прислать событие заново.

Права и ответственность

• URL виден только тем, кто вправе менять автопилот — его владельцу и администраторам.
• Срабатывание идёт с правами того, кто настроил автопилот. Вебхук не расширяет доступ: агент сделает ровно то, что позволено этому человеку.
• Один источник — один автопилот. Так проще отзывать доступ: смена адреса затрагивает только эту интеграцию, а журнал доставок остаётся читаемым.

Типовые сценарии

• Мониторинг → инцидент. Алерт создаёт задачу, агент собирает сводку по инциденту и предлагает план коммуникации.
• CI/CD → разбор сбоя. Упавшая сборка приносит лог, агент классифицирует причину и заводит задачу нужной команде.
• ATS или CRM → первичная обработка. Отклик или заявка попадают в Баунс, агент готовит резюме и передаёт человеку на решение.
• Форма на сайте → обращение. Заявка становится задачей с уже разобранными полями.

Чего вебхук не делает

• Не фильтрует события по типу. Все запросы на один адрес доходят до исполнителя; если источник шлёт много разных событий, разбор делает агент по промпту или воркфлоу по условию.
• Не запускает воркфлоу напрямую — вебхук всегда висит на автопилоте, а тот уже запускает воркфлоу. Это сделано, чтобы входящие события имели одну точку входа и один журнал.
• Не отдаёт результат работы обратно синхронно. Ответ 202 означает «принято»; результат агента приходит в задачу, а вашей системе его отдают, если это отдельно собрано воркфлоу.

Далее

• Автопилоты — что именно запускает событие и как устроены запуски.
• Воркфлоу — обработка события с условиями и внешними вызовами.
• Коннекторы — обратное направление: доступ агента в ваши системы.