TRIBLY
Документация Tribly → Вебхуки каналов

Вебхуки каналов

Вебхук канала — секретный URL, на который внешняя система (GitLab, Zabbix, Grafana, собственный скрипт) шлёт уведомление, и оно появляется в канале от имени самого канала. Формат входа — Slack/Mattermost Incoming Webhooks ({"text": …, "attachments": […]}), то есть почти любая интеграция, которая умеет слать в Slack, работает здесь без переделки.

В отличие от Bot API (страница «Боты и Bot API»), здесь не нужен бот: создаёте вебхук в настройках канала, копируете URL и вставляете его во внешний сервис. Автором сообщения становится botMother — системный бот, который может писать в любой канал без приглашения. Участники получают уведомление и непрочитанное, как от обычного сообщения.

Создание

1. Откройте настройки канала (сведения о канале → «Вебхуки»). Доступно только владельцу канала или суперадмину — секрет даёт право писать в канал от его имени, это власть владельца.

2. Нажмите «Создать вебхук». Можно задать метку («GitLab», «Мониторинг») — она видна только в списке.

3. Скопируйте URL. Он имеет вид https://<сервер>/api/v1/hooks/<секрет>. Секрет — 64 символа: перебор невозможен, а утечка URL равна праву писать в канал, поэтому не публикуйте его в открытых местах.

4. Вставьте URL во внешний сервис и настройте формат сообщения (см. ниже).

У канала может быть до 10 вебхуков — например, свой на проект GitLab и свой на мониторинг. Каждый имеет свою статистику (когда последний раз срабатывал и сколько раз).

Формат сообщения

Тело запроса — JSON в формате Slack Incoming Webhooks:

{ "text": "Деплой 2.4.1 завершён" }
``

Поле `text` поддерживает Markdown. Оповещение-карточка:

{ "text": "Критическая ошибка на проде", "attachments": [ { "title": "Zabbix · Production-01", "text": "CPU Load > 95% пять минут", "color": "danger", "fields": [{"title": "Хост", "value": "db-master-01", "short": true}] } ] } ``

Используются text и attachments (внутри — title, text, color, fields). Цвет color рисует полоску слева: #RRGGBB или слова good, warning, danger, info. Поля username, icon_emoji, icon_url принимаются ради совместимости, но игнорируются — отправитель всегда botMother.

Принимаются оба формата отправки:

  • сырой JSON (Content-Type: application/json) — как шлют современные системы;
  • form-encoded payload=<json> (Content-Type: application/x-www-form-urlencoded) — legacy-формат Slack/Mattermost, который до сих пор шлют Zabbix, часть интеграций GitLab и старые скрипты.

Если запрос отклонён с 400 «Пустое сообщение» — внешняя система прислала JSON БЕЗ поля text (например, generic-webhook GitLab). В этом случае настройте интеграцию на формат Slack/Mattermost или добавьте поле text в тело.

Пример: GitLab

В настройках проекта GitLab: Settings → Integrations → Webhooks (или Settings → Integrations → Mattermost notifications — формат тот же):

  • URL: https://<сервер>/api/v1/hooks/<секрет> (скопируйте из настроек канала).
  • События: выберите нужные (push, pipeline, issue, merge request…).

GitLab шлёт JSON с полями text и attachments — они склеиваются в одно сообщение канала.

Пример: curl (проверка)

curl -X POST https://<сервер>/api/v1/hooks/<секрет> \\
  -H "Content-Type: application/json" \\
  -d '{"text":"Вебхук работает"}'
``

Успешный ответ — `ok` (200). Пустой `text` без вложений — ошибка 400.

---

## Как это работает под капотом

* Сообщение создаётся от имени botMother — системного бота, который может писать в любой канал без приглашения (проверка членства для неё делает исключение). У сообщения должен быть автор, иначе клиент не показывает непрочитанное и не будит телефон.
* Приём идёт по секрету в URL, без заголовков авторизации: внешние системы шлют вебхуки голым POST. Частота ограничена общим лимитером сервера (по IP).
* Удаление вебхука не трогает уже доставленные сообщения. Удаление канала уносит вебхуки каскадом.

---

## Диагностика

| Симптом | Что проверить |
|---|---|
| 404 при отправке | Вебхук удалён или секрет скопирован не полностью |
| 403 «канал в архиве» | Архив запрещает запись; разархивируйте канал |
| 400 «пустое сообщение» | В запросе нет `text` и нет вложений |
| Сообщение есть, но без уведомления | Проверьте настройки уведомлений канала на устройстве |
| Сервер просит подождать | Слишком частые запросы — снизьте темп |

Смежные страницы: «Боты и Bot API», «Интеграции и вебхуки».