Входящие вебхуки

Вебхук — адрес, на который ваша система отправляет запрос, а Kontext превращает его в сообщение в канале. Так в канал попадают новости о сборках и деплое, алерты мониторинга, ошибки, платежи, заявки с форм.

Создать

1. Откройте настройки пространства → вкладка «Интеграции» → «Вебхуки». Раздел видят те, у кого в роли есть право управлять каналами, а администраторы — всегда.
2. Выберите источник: GitLab, GitHub, Sentry, Alertmanager, Grafana — или «Slack-совместимый» для всего остального.
3. Задайте название и канал. Название показывается первой строкой сообщения, если не совпадает с именем отправителя, — например, «Сборки» в сообщениях от «Jenkins». Выбрать можно только канал, в котором вы состоите сами.
4. Скопируйте адрес, а у GitLab и GitHub — и секрет. Они показываются один раз: сохраните их в настройках системы, которая будет отправлять сообщения.

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

Потеряли адрес — отзовите вебхук и заведите новый.

Готовые источники

• Подпись проверяется, если у вебхука есть секрет. У GitLab и GitHub секрет создаётся сразу, вместе с адресом. У Sentry секрет выдаёт сам Sentry: его вставляют вторым шагом, а до этого подпись не проверяется. У Alertmanager и Grafana секрет можно добавить кнопкой, по желанию; без секрета ключом служит сам адрес. Повторную доставку того же события Kontext отбрасывает у всех источников.
• У каждого MR, PR, ошибки или алерта — свой тред. Все события одного merge request, pull request, ошибки или алерта собираются в его тред, а основное сообщение обновляется на месте. Пайплайн для MR и прогон Actions для PR попадают в тред этого MR или PR, а не отдельным сообщением в канал.
• Лишнее молча пропускается: незнакомые события и события, не отмеченные в настройке вебхука, в канал не попадают, но и ошибкой не считаются.
• Алерт может разобрать агент. Агент пространства срабатывает на подходящие сообщения канала, смотрит логи и метрики в Elasticsearch, Prometheus, Loki или Grafana — только на чтение — и пишет разбор в тред алерта. По желанию он упоминает дежурного и заводит задачу. Агента настраивает администратор во вкладке «Агенты», подробнее — ИИ в Kontext.

Формат запроса

«Slack-совместимый» вебхук принимает запросы POST в том же виде, в каком системы отправляют их в Slack или Mattermost, — менять шаблоны не нужно:

• JSON с полем text: {"text": "Сборка #412 упала"}, а также body или message;
• вложения (attachments) и блоки Slack — они показываются карточкой: цветная полоса, поля, картинка;
• форму с полем payload=…, как у интеграции GitLab «Mattermost notifications»;
• разметку Slack и Mattermost: ссылки <адрес|текст> становятся обычными ссылками;
• просто текст в теле запроса.

Текст поддерживает то же форматирование, что и обычные сообщения, включая блоки кода. Текст длиннее 16 000 символов обрезается.

Примеры

curl

curl -X POST "$KONTEXT_WEBHOOK" \
  -H "Content-Type: application/json" \
  -d '{"text": "Деплой на прод завершён"}'

GitHub Actions

- name: Сообщить в Kontext
  if: failure()
  run: |
    curl -X POST "${{ secrets.KONTEXT_WEBHOOK }}" \
      -H "Content-Type: application/json" \
      -d "{\"text\": \"Сборка упала: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID\"}"

GitLab CI

notify:
  stage: .post
  when: on_failure
  script:
    - 'curl -X POST "$KONTEXT_WEBHOOK" -H "Content-Type: application/json" -d "{\"text\": \"Пайплайн упал: $CI_PIPELINE_URL\"}"'

Как это работает

• От чьего имени приходят сообщения. По умолчанию — от имени самого сервиса: события GitHub приходят от «GitHub» с его значком, алерты Grafana — от «Grafana». У своего вебхука можно задать имя и загрузить картинку, например «Jenkins» с его логотипом. В поле «Писать от имени» можно выбрать и другое: вас самих или бота пространства. Сервис, как и бот, не зависит от того, в каких каналах сейчас человек, который завёл вебхук, и работает ли он ещё в компании. Подробнее о ботах — в разделе API.
• @channel и @here из тела запроса видны в сообщении, но уведомления по ним приходят, только если у вебхука отмечено «Будить канал». У алертов и Sentry с этой галочкой весь канал получает уведомление о новой тревоге.
• Ограничение — 30 сообщений в минуту на «Slack-совместимый» вебхук и 120 событий в минуту на готовый источник. Этого хватает на пачку упавших сборок, и при этом канал не завалит сообщениями.
• Отозванный вебхук отвечает ошибкой 404 — так ваша система узнает, что вебхука больше нет.
• Если вебхук пишет от вашего имени и вас убрали из пространства, он перестаёт работать: писать от имени человека без доступа нельзя. Если вы вышли из канала или канал в архиве, вебхук отвечает ошибкой 403 с объяснением причины, и это же объяснение видно в настройках.
• Адрес — это ключ. Храните его в секретах CI, а не в коде репозитория.