Вебхуки
Вебхук — это адрес, на который внешняя система присылает события. Kizora проверяет подпись, ставит событие в очередь и публикует его в ваш канал.
Как это работает
внешняя система
↓
адрес вебхука Kizora
↓
проверка подписи и свежести
↓
очередь
↓
сообщение в канал DiscordКогда использовать
- Коммиты и пул-реквесты репозитория в канал разработки.
- Тревоги мониторинга в служебный канал.
- События своего сервиса, у которого есть исходящие вебхуки.
Перед настройкой
- Модуль Интеграции включён.
- Есть канал для публикаций.
- У бота есть Отправка сообщений и Встроенные ссылки.
Как создать
Через панель. Сервер, раздел Ленты и вебхуки: имя, канал, источник.
Через Discord. /вебхук создать — имя, канал, источник. Секрет придёт в личные сообщения.
Вебхуков на сервер — до 10.
Источники
| Источник | Подпись | Заголовок идентификатора |
|---|---|---|
| GitHub | X-Hub-Signature-256 вида sha256=hex | X-GitHub-Delivery |
| GitLab | Токен в X-Gitlab-Token | Idempotency-Key или X-Gitlab-Event-UUID |
| Свой источник | X-Kizora-Signature | X-Kizora-Delivery |
События, которые понимаются
| Событие GitHub | Событие GitLab | Как показывается |
|---|---|---|
push | Push Hook | Коммиты |
pull_request | Merge Request Hook | Пул-реквесты |
issues | Issue Hook | Задачи |
release | Release Hook | Релизы |
deployment_status | Pipeline Hook | Выкладки |
Остальные события принимаются как «прочее», если вы не отключили их показ.
Своя подпись
Для источника «свой» Kizora ждёт три заголовка:
X-Kizora-Signature: <hex hmac-sha256>
X-Kizora-Timestamp: <момент отправки>
X-Kizora-Delivery: <уникальный идентификатор доставки>Подписывается строка <отметка времени>.<идентификатор доставки>.<тело> ключом-секретом, алгоритм HMAC-SHA256, результат в шестнадцатеричном виде.
Идентификатор внутри подписи — не украшение: заголовок, которого в подписи нет, снимает тот, кто записал запрос, и защита от повтора обходится удалением одной строки.
Защита от повторов
- Отметка времени должна отличаться от текущего момента не больше чем на минуту. Без этого перехваченный запрос годен вечно.
- Идентификатор доставки запоминается: второй запрос с тем же идентификатором отмечается как дубликат и не публикуется повторно.
- Подпись сравнивается за постоянное время — посимвольное сравнение выдавало бы длину общего префикса временем ответа.
Тело запроса — до 256 КБ.
Ответ отправителю
Kizora отвечает 202 и на «принято», и на «сервер такое не показывает»: для отправителя это одно и то же — запрос получен и разобран. Отказ приходит только при неверном токене, неверной подписи, устаревшей отметке времени или слишком большом теле.
Права
- Kizora:
integrations.manage. Право помечено как доступ к личным данным: оно открывает секреты вебхуков. - Discord у бота: Отправка сообщений, Встроенные ссылки.
Хранение секрета
Секрет хранится в базе в зашифрованном виде. Хранить его приходится: проверить HMAC чужого запроса без ключа нельзя, а схема без настоящей подписи была бы только её видимостью.
Практическое следствие записано прямо: доступ к базе означает доступ к каналам, куда пишут эти вебхуки.