Руководство по вебхукам AgentVera

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

У каждого вебхука есть секретный URL. На запрос по этому URL AgentVera может:

• Создать канбан-карточку на выбранной вами доске и в выбранной колонке, при желании с метками.
• Создать задачу для агента: Claude или Codex, который работает либо на вашем Runner, либо в настольном приложении, где открыт проект карточки.

Когда агент завершает ход, сводка результата записывается на карточку как внутренний комментарий от «AgentVera». Следить за задачами в реальном времени можно на app.agentvera.dev/tasks.

Создание вебхука

Вебхуки создают владельцы и администраторы организации. На app.agentvera.dev/webhooks нажмите «Yeni webhook» (новый вебхук) и выполните следующие шаги:

1. Дайте вебхуку имя.
2. Действие с карточкой: выберите доску и колонку, где будет создана карточка.
3. Действие с задачей: выберите тип агента (Claude или Codex) и цель. Цель — конкретный Runner (при желании с рабочей папкой) или «Proje» (проект), то есть настольное приложение, в котором открыт проект карточки. Задачи проекта всегда привязаны к карточке.
4. Шаблон: напишите заголовок карточки, описание и промпт агента с плейсхолдерами {{…}}.
5. Фильтр (необязательно): обрабатывать только определённые запросы.
6. Подпись (рекомендуется): выберите проверку GitHub или универсальную HMAC-SHA256.
7. Сохраните. URL вебхука и секрет подписи показываются только один раз; скопируйте оба.

URL или секрет можно сменить позже; старый URL перестаёт работать сразу.

Шаблоны и плейсхолдеры

Плейсхолдеры берут значения из входящего запроса:

• {{body.issue.title}}: поля JSON-тела в виде пути через точки. Для элементов массива используйте числа: {{body.commits.0.id}}.
• {{headers.x-github-event}}: заголовки запроса в нижнем регистре.
• {{query.foo}}: параметры запроса в URL.

Отсутствующее значение становится пустым; объекты вставляются как JSON. Пробелы в заголовке карточки сворачиваются до одиночных, а длина заголовка ограничена 300 символами. Описание карточки очищается; промпт передаётся агенту в точности как написан.

Фильтр

Фильтр требует, чтобы значение в запросе (path) было равно заданному или входило в разрешённые вами значения. Например, чтобы обрабатывать только новые issues GitHub, укажите path body.action и значение opened. Запросы, которые не подходят, записываются в журнал как «ignored» и не создают ни карточки, ни задачи.

Проверка подписи

• GitHub: заголовок X-Hub-Signature-256 проверяется с помощью секрета подписи.
• Универсальная HMAC-SHA256: шестнадцатеричная подпись тела ожидается в заголовке, имя которого вы задаёте; префикс sha256= тоже принимается.

Всегда используйте подпись, если источник её поддерживает. Для источников, которые не умеют подписывать, безопасность держится на секретном URL; если он утёк, смените его.

Пример: задачи из issues GitHub

1. В репозитории GitHub откройте Settings → Webhooks → Add webhook.
2. Укажите URL вебхука AgentVera как Payload URL, application/json как Content type и секрет подписи как Secret.
3. Выберите событие «Issues» и сохраните.

Шаблон в AgentVera:

Title:       {{body.issue.title}}
Description: {{body.issue.body}}
Filter:      body.action = opened
Prompt:
GitHub issue #{{body.issue.number}}: {{body.issue.title}}

{{body.issue.body}}

Изучи эту ошибку, исправь её и запусти тесты.

Sentry и другие JSON-источники

Направьте любой сервис на URL вебхука. Если источник умеет подписывать, используйте универсальную HMAC-SHA256; если нет — полагайтесь на секретный URL. Сопоставьте поля, которые отправляет источник, с шаблоном через плейсхолдеры. Чтобы попробовать из своей системы:

curl -X POST "https://app.agentvera.dev/hooks/<id>/<secret>" \
  -H "content-type: application/json" \
  -d '{"title": "Checkout page returns 500", "detail": "..."}'

Запросы, ответы и лимиты

• Только POST; тело — JSON или form-encoded, до 1 МБ.
• 60 запросов в минуту на вебхук, 600 в минуту на IP.
• 202: принято (запросы, отфильтрованные фильтром, тоже получают 202).
• 401: неверная подпись.
• 403: тариф организации не включает вебхуки.
• 404: неверный URL, отключённый вебхук или приостановленная организация (во всех случаях ответ одинаковый).
• 413: слишком большое тело. 429: превышен лимит запросов.

Доставки и задачи

• Каждый запрос записывается в доставки вебхука со статусом ok, ignored, rejected или failed, а также с отметкой, были ли созданы карточка или задача.
• Содержимое запроса (тело, заголовки и query; заголовки Authorization, cookie и подписи исключены) хранится 7 дней, и в течение этого времени его можно повторно обработать с текущим шаблоном — это помогает после исправления шаблона. Затем содержимое удаляется, а сводка остаётся.
• app.agentvera.dev/tasks показывает задачи в реальном времени: queued, claimed, running, done или failed. Администраторы могут отменять задачи.
• Если Runner офлайн, задача ждёт в очереди и отправляется, когда runner подключится. Задача, которая 30 минут не продвигается, один раз возвращается в очередь; во второй раз она помечается как failed.

Безопасность

Содержимое вебхука попадает в промпт агента как есть. Любой, кто может написать issue в репозитории, мог бы попытаться давать агенту указания.

• Подключайте только источники и репозитории, которым доверяете.
• Используйте фильтры, чтобы сузить круг обрабатываемых запросов.
• На Runner используйте roots, чтобы ограничить папки, доступные агентам.
• Всегда используйте подпись, если источник её поддерживает; URL — секрет, смените его, если он утёк.
• Содержимое запросов никогда не записывается в журналы; секретная часть URL в журналах скрывается.