Wiki

Веб-хуки

Исходящие уведомления по репозиторию (Discord, Slack, Teams, custom) при check-in, check-out и сводках активности. Создание, формат сообщений, переменные шаблона, защита от SSRF.

Введение

Веб-хук отправляет исходящее уведомление во внешнюю службу (Discord, Slack, Microsoft Teams, или URL по вашему выбору) каждый раз, когда в репозитории происходит событие: check-in, check-out или периодическая сводка активности. Это самый простой способ держать команду в курсе, не открывая клиент: сообщение приходит в ваш канал, когда кто-то отправляет работу.

Веб-хуки настраиваются для каждого репозитория, в панели администрирования настольного клиента, на вкладке Webhooks. У репозитория может быть несколько веб-хуков (например, один в Discord для всей команды, один в приватный Slack для лидов).

Доступ и роли

Управление веб-хуками доступно только администраторам репозитория: суперадминистратору (роль admin) в любом репозитории или project_admin в репозиториях, которыми он управляет. Другие роли эту вкладку не видят.

Полезно знать Вкладка Webhooks использует систему множественных веб-хуков (несколько записей на репозиторий). Старое уведомление Discord с единственным URL всё ещё существует на стороне сервера для совместимости, но оно не отображается на этой новой вкладке: используйте описанные здесь веб-хуки.

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

Форма Add Webhook: Name, URL, Type (discord/slack/teams/custom), флажки Events, переключатель Enabled.

Откройте панель администрирования, выберите репозиторий, затем вкладку Webhooks.
Нажмите Add Webhook.
Заполните поля, затем Create.

Поле	Значение
Name	Метка, чтобы его узнать (напр. `Discord équipe`). Обязательно.
URL	URL веб-хука, предоставленный целевой службой. Обязательно. См. Безопасность об отклоняемых URL.
Type	`discord`, `slack`, `teams` или `custom`.
Events	Один или несколько из `checkin`, `checkout`, `activity_summary`. Хотя бы один обязателен.
Enabled	Переключатель активации (виден при редактировании и из списка).

Чтобы получить URL на стороне Discord: Настройки канала → Интеграции → Веб-хуки → Новый веб-хук → Копировать URL веб-хука. На стороне Slack: создайте Incoming Webhook в настройках приложения Slack. На стороне Teams: Соединители → Incoming Webhook на канале.

Руководство: веб-хук Discord

Это самый распространённый случай. Часть «получить URL» полностью выполняется в Discord, всего один раз.

На стороне Discord: получить URL

Откройте Discord и перейдите на свой сервер. Выберите (или создайте) текстовый канал, который будет получать уведомления, например #uversion.
Наведите курсор на название канала и нажмите значок шестерёнки («Редактировать канал»).
В меню слева откройте вкладку Интеграции.
Нажмите Веб-хуки, затем Новый веб-хук. Discord автоматически создаст его, привязанным к этому каналу.
Нажмите созданный веб-хук, чтобы открыть его. Дайте ему имя (например uVersion) и проверьте, что целевой канал верный. Изображение аватара необязательно.
Нажмите Копировать URL веб-хука. URL выглядит так: https://discord.com/api/webhooks/123456789/AbCdEf....

Держите этот URL в секрете Любой, у кого есть URL, может публиковать сообщения в вашем канале. Не коммитьте его в репозиторий и не делитесь им публично. Если он утёк, удалите веб-хук на стороне Discord и создайте новый.

На стороне uVersion: подключить URL

В настольном клиенте откройте панель администрирования, выберите репозиторий, затем вкладку Webhooks.
Нажмите Add Webhook.
Name: метка для вас (напр. Discord équipe).
URL: вставьте URL, скопированный из Discord.
Type: выберите discord (необходимо, чтобы сообщение было оформлено как embed Discord).
Events: отметьте нужные события, например checkin.
Нажмите Create.
В строке веб-хука нажмите Send test: тестовое сообщение должно появиться в канале Discord в течение нескольких секунд.

Если тест завершается с HTTP-кодом 401 или 404, URL неверен или веб-хук был удалён на стороне Discord: скопируйте URL заново. Если тест зелёный, но ничего не приходит, проверьте, что вы смотрите в нужный канал и что веб-хук не был отключён в Discord.

Типы и форматы

Type определяет, как uVersion форматирует сообщение перед отправкой. Выберите тот, что соответствует службе, на которую указывает URL, иначе сообщение придёт неправильно оформленным (или будет отклонено службой).

Type	Отправляемый формат
`discord`	Embed Discord (заголовок, цвет, поля).
`slack`	Полезная нагрузка Slack (блоки сообщения).
`teams`	Карточка Microsoft Teams (MessageCard).
`custom`	Тело JSON, полностью определяемое вами: см. Пользовательские веб-хуки.

События

Событие	Срабатывает, когда…
`checkin`	Пользователь отправляет коммит в репозиторий.
`checkout`	Пользователь блокирует (check-out) один или несколько файлов.
`activity_summary`	Планировщик сервера формирует периодическую сводку активности (ежедневную / еженедельную).

Отмечайте только то, что нужно вашему каналу. В крупной студии checkout может быть шумным: многие команды оставляют только checkin и activity_summary.

Пользовательские веб-хуки

С типом custom появляются два дополнительных поля: Custom Headers (JSON) и Custom Template (JSON). Они позволяют интегрировать любую службу, принимающую POST в формате JSON.

Template

Шаблон представляет собой отправляемое тело JSON. uVersion заменяет в нём переменные в двойных фигурных скобках значениями события. Пример:

{"text": "{{event_type}} par {{username}} dans {{repository}}"}

Доступные переменные:

Переменная	Содержимое
`{{event_type}}`	Тип события (`checkin`, `checkout`, `activity_summary`).
`{{repository}}`	Имя репозитория.
`{{username}}`	Пользователь, вызвавший событие.
`{{message}}`	Сообщение коммита (для check-in).
`{{file_count}}`	Число затронутых файлов.
`{{commit_hash}}`	Хеш коммита.
`{{timestamp}}`	Метка времени события.

Headers

Объект JSON из HTTP-заголовков, добавляемых к запросу, например токен аутентификации:

{"Authorization": "Bearer VOTRE_JETON"}

По умолчанию {} (без заголовков). Заголовки, зарезервированные для транспорта (host, content-length, transfer-encoding, connection) удаляются автоматически и не могут быть переопределены.

Обязателен корректный JSON Поля Headers и Template проверяются при сохранении. Некорректный JSON блокирует сохранение с явным сообщением («Invalid JSON in headers» / «… template»). Проверьте фигурные скобки и кавычки.

Тест, включение, удаление

Строка веб-хука с кнопкой « Send test » и, в идеале, тестовым сообщением, полученным в Discord.

Каждый веб-хук в списке предлагает следующие действия:

Send test (значок самолёта): отправляет тестовое уведомление в службу и показывает результат в строке (зелёная галочка или крест). Полезно проверить URL и тип, прежде чем на него полагаться.
Переключатель: включает / отключает веб-хук без удаления.
Edit: изменить любое поле.
Delete: окончательное удаление (запрашивается подтверждение).

Тест не возвращает тело ответа В случае сбоя uVersion сообщает только HTTP-код, возвращённый службой (напр. «Webhook returned HTTP 404»), но никогда содержимое ответа. Это сделано намеренно (см. Безопасность). Если тест не проходит, проверьте сначала URL и тип, затем права веб-хука на стороне службы.

Безопасность: защита от SSRF

Веб-хук заставляет сервер отправить HTTP-запрос. Чтобы вредоносный URL не мог использоваться для зондирования внутренней сети сервера (атака SSRF), uVersion применяет строгую защиту при создании, при изменении и при тесте:

Схема должна быть http или https. Любая другая схема отклоняется.
Имя хоста разрешается через DNS, и проверяется каждый полученный IP-адрес. Веб-хук отклоняется, если один из них указывает на непубличный адрес: loopback, частные сети (RFC1918), link-local, broadcast, диапазон CGNAT 100.64.0.0/10, облачные метаданные 169.254.169.254, ULA / IPv6 link-local и их эквиваленты IPv4-mapped-IPv6.
HTTP-перенаправления не отслеживаются (поэтому 307 на внутренний хост не может обойти защиту).
Тело ответа вышестоящего сервера никогда не возвращается клиенту (нет SSRF-оракула).

На практике: URL веб-хука должен указывать на публичную службу (Discord, Slack, Teams или ваш собственный эндпоинт, доступный из Интернета). URL на localhost, частный IP (10.x, 192.168.x, 172.16-31.x) или внутреннюю службу отклоняется с сообщением «Webhook URL refused: …».

Частые ошибки

Тип не соответствует службе

Отправка формата Discord на URL Slack (или наоборот) даёт неправильно оформленное сообщение или отказ на стороне службы. Поле Type должно соответствовать URL. Если сомневаетесь, выполните Send test.

Не отмечено ни одного события

Веб-хук без события никогда не срабатывает. Клиент блокирует сохранение, пока не выбрано ни одного события («At least one event is required»).

Внутренний URL отклонён

Если вы тестируете против службы на своей машине или в своей LAN, защита от SSRF её отклоняет. Опубликуйте службу на публичном URL (или через туннель), чтобы использовать её как цель веб-хука.

Забытый отключённый веб-хук

Отключённый веб-хук остаётся в списке, но ничего не отправляет. Если уведомления затихли, сначала проверьте переключатель активации, прежде чем подозревать URL.