Канал Slack#

Slack — это исходящий канал уведомлений.

IncidentRelay поддерживает два режима доставки в Slack:

Режим входящего вебхука для односторонних уведомлений.
Режим Bot API с интерактивными кнопками Acknowledge, Resolve, Shelve 1h и Unshelve и обновлением сообщений.

Интерактивные действия Bot API можно получать двумя способами:

через HTTP Request URL с signing secret;
через Socket Mode по исходящему WebSocket-соединению с токеном уровня приложения (app-level token).

Режим Bot API рекомендуется, когда ответственные должны управлять алертами прямо из Slack.

Режим входящего вебхука#

Используйте этот режим, когда вам нужно только отправлять уведомления.

Создайте входящий вебхук в Slack и настройте канал с параметрами:

{
  "mode": "webhook",
  "webhook_url": "https://hooks.slack.com/services/..."
}

Сообщения входящего вебхука не могут обновляться IncidentRelay после того, как алерт подтверждён или разрешён.

Режим Bot API#

Режим Bot API поддерживает:

отправку уведомлений об алертах с помощью Block Kit;
кнопки Acknowledge, Resolve, Shelve 1h и Unshelve;
обновление исходного сообщения Slack после ACK, Resolve, Shelve или Unshelve;
удаление действий после разрешения алерта;
опциональную атрибуцию пользователю IncidentRelay.

Конфигурация HTTP-действий:

{
  "mode": "bot_api",
  "connection_mode": "http",
  "bot_token": "xoxb-...",
  "channel_id": "C0123456789",
  "signing_secret": "..."
}

Конфигурация Socket Mode:

{
  "mode": "bot_api",
  "connection_mode": "socket_mode",
  "bot_token": "xoxb-...",
  "app_token": "xapp-...",
  "channel_id": "C0123456789"
}

Создание приложения Slack#

Откройте страницу управления приложениями Slack.
Создайте новое приложение для целевого рабочего пространства.
Откройте OAuth & Permissions.
Добавьте scope токена бота:

``text chat:write ``

Установите или переустановите приложение в рабочем пространстве.
Скопируйте Bot User OAuth Token. Обычно он начинается с xoxb-.
Пригласите бота в канал Slack, который будет получать алерты IncidentRelay.

IncidentRelay использует chat.postMessage для отправки сообщений и chat.update для обновления существующих сообщений.

Выбор транспорта интерактивных действий#

HTTP Request URL#

Используйте режим HTTP, когда Slack может обращаться к IncidentRelay по публичному HTTPS.

Откройте Interactivity & Shortcuts в настройках приложения Slack и включите интерактивность.

Укажите Request URL:

https://incidentrelay.example.com/api/integrations/slack/actions

Замените https://incidentrelay.example.com на настроенный публичный URL IncidentRelay.

IncidentRelay проверяет каждое взаимодействие, используя:

X-Slack-Signature;
X-Slack-Request-Timestamp;
signing secret приложения Slack.

Запросы старше пяти минут отклоняются.

Поиск signing secret#

Откройте Basic Information в настройках приложения Slack и найдите App Credentials.

Скопируйте Signing Secret в конфигурацию канала Slack в IncidentRelay.

Не используйте старый verification token Slack. IncidentRelay проверяет подписанные запросы с помощью signing secret.

Socket Mode#

Socket Mode рекомендуется для приватных сетей, установок за NAT и с ограничениями межсетевого экрана. IncidentRelay открывает исходящее WebSocket-соединение к Slack, поэтому для кнопок действий не требуется публичный Request URL или public_base_url.

В настройках приложения Slack:

Откройте Settings → Socket Mode и включите Socket Mode.
Откройте Basic Information → App-Level Tokens.
Сгенерируйте токен со scope connections:write.
Скопируйте токен, начинающийся с xapp-.
Оставьте Interactivity & Shortcuts включённым; в Socket Mode Request URL не требуется.

В IncidentRelay выберите Bot API → Socket Mode и введите токен бота, токен уровня приложения и ID канала Slack.

Воркер Slack должен быть запущен. Docker Compose включает incidentrelay-slack. Для systemd:

sudo cp etc/systemd/incidentrelay-slack-worker.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now incidentrelay-slack-worker

Проверка статуса:

systemctl status incidentrelay-slack-worker
journalctl -u incidentrelay-slack-worker -f

Одно соединение Socket Mode открывается для каждого отдельного токена уровня приложения. Несколько каналов Slack в IncidentRelay могут использовать одно и то же приложение Slack и токен уровня приложения.

Поиск ID канала#

Откройте целевой канал Slack и скопируйте его ID канала.

Используйте ID, например:

C0123456789

Не вводите отображаемое имя канала.

Бот должен иметь возможность публиковать сообщения в настроенном канале.

Настройка IncidentRelay#

В IncidentRelay:

Откройте Channels.
Создайте или отредактируйте канал Slack.
Выберите Bot API.
Введите токен бота и ID канала.
Выберите способ подключения интерактивных действий:
HTTP Request URL и введите Signing Secret; либо
Socket Mode и введите App-Level Token.
Сохраните канал.
Привяжите канал к нужному маршруту.
Отправьте тестовое уведомление или реальный тестовый алерт.

Для интерактивных HTTP-действий убедитесь, что Slack может обращаться к POST /api/integrations/slack/actions через публичный HTTPS. public_base_url рекомендуется для ссылки Open alert in IncidentRelay, но не используется для проверки или обработки действий кнопок Slack. Socket Mode не требует, чтобы эндпоинт действий был публично доступен.

Атрибуция пользователю#

Пользователь IncidentRelay может иметь ID пользователя Slack в своём профиле.

Когда ответственный нажимает Acknowledge, Resolve, Shelve 1h или Unshelve, IncidentRelay считывает ID пользователя Slack из полезной нагрузки взаимодействия и пытается сопоставить его с активным пользователем IncidentRelay.

Интерактивные действия требуют Slack user ID, связанного с активным IncidentRelay user с responder-доступом к команде алерта. Несвязанные или неавторизованные пользователи отклоняются.

Поведение сообщений#

Для активного алерта сообщение Slack содержит:

заголовок и описание алерта;
статус, важность и приоритет;
команду, сервис и назначенного ответственного;
ссылки на сервис и runbook, когда они настроены;
ссылку на алерт в IncidentRelay;
кнопки Acknowledge, Resolve и Shelve 1h.

После подтверждения:

исходное сообщение обновляется;
статус меняется на acknowledged;
кнопка Acknowledge удаляется;
кнопки Shelve 1h и Resolve остаются доступными.

После разрешения:

исходное сообщение обновляется;
статус меняется на resolved;
все кнопки действий удаляются.

Режим входящего вебхука только отправляет сообщения и не поддерживает эти обновления.

Кнопка теста#

Тест канала проверяет, что IncidentRelay может отправить сообщение, используя настроенные учётные данные Slack.

Он не подтверждает, что:

канал привязан к правильному маршруту;
матчеры маршрута принимают реальный алерт;
фильтры важности пропускают алерт;
Slack может обращаться к эндпоинту интерактивных действий.

Используйте реальный тестовый алерт для проверки полного рабочего процесса.

Устранение неполадок#

Slack возвращает `invalid_auth`#

Проверьте, что:

токен начинается с xoxb-;
приложение установлено в правильном рабочем пространстве;
токен не был отозван;
приложение было переустановлено после изменения scope.

Slack возвращает `not_in_channel`#

Пригласите бота в настроенный канал Slack.

Сообщения отправляются, но кнопки не работают#

Для обоих транспортов убедитесь, что выбран режим Bot API, а в приложении Slack включена настройка Interactivity & Shortcuts.

Для HTTP-действий также проверьте, что:

Request URL указывает на /api/integrations/slack/actions;
эндпоинт IncidentRelay публично доступен по HTTPS;
signing secret совпадает с приложением Slack;
обратные прокси сохраняют исходное тело запроса и заголовки подписи Slack.

Для Socket Mode также проверьте, что:

Socket Mode включён;
app-level token начинается с xapp- и имеет разрешение connections:write;
воркер Slack запущен и имеет исходящий доступ по HTTPS/WebSocket.

Действие Slack отклоняется как устаревшее#

Запросы взаимодействий Slack старше пяти минут отклоняются.

Проверьте синхронизацию системного времени на сервере IncidentRelay и обратном прокси.

Действие Slack отклоняется из-за несоответствия канала#

ID канала Slack во взаимодействии должен совпадать с ID канала, настроенным в IncidentRelay.

Проверьте, что уведомление было отправлено в ожидаемый канал Slack и что конфигурация канала IncidentRelay не была изменена.

Сообщения не обновляются#

Обновление сообщений требует режима Bot API.

Проверьте, что при исходной доставке были сохранены оба значения:

ID канала Slack;
временная метка сообщения Slack.

Доставки через входящий вебхук не могут обновляться.

Замечания по безопасности#

Держите токен бота, app-level token и signing secret в тайне.
Не включайте эти значения в журналы, скриншоты или обращения в поддержку.
Ротируйте любой раскрытый токен бота, app-level token или signing secret.
Открывайте наружу только необходимые HTTPS-эндпоинты IncidentRelay.
Держите время сервера синхронизированным, чтобы проверка временных меток работала корректно.

Справочные материалы Slack#

У воркера Socket Mode нет соединений#

Проверьте, что:

канал Slack включён;
connection_mode равен socket_mode;
токен приложения начинается с xapp-;
у токена приложения есть connections:write;
Socket Mode включён в приложении Slack;
служба или контейнер воркера Slack запущены;
разрешены исходящие HTTPS- и WebSocket-соединения к Slack.

Журналирование воркера Slack#

Воркер Socket Mode использует роль журналирования slack и пишет JSON-логи в отдельный файл. Настройте путь в incidentrelay.conf:

[logging]
slack_worker_file = /var/log/incidentrelay/incidentrelay-slack-worker.log

Файл содержит события oncall.slack, oncall.slack.socket и события уровня воркера oncall.error. Штатное правило logrotate уже покрывает этот файл через /var/log/incidentrelay/*.log.

Для установок systemd:

tail -f /var/log/incidentrelay/incidentrelay-slack-worker.log
journalctl -u incidentrelay-slack-worker -f

Для Docker Compose:

docker compose exec incidentrelay-slack \
  tail -f /var/log/incidentrelay/incidentrelay-slack-worker.log

Shelving#

Slack Bot API поддерживает Shelve 1h и Unshelve. Incoming Webhook остаётся односторонним и интерактивный Shelve не поддерживает. Slack user должен быть связан с IncidentRelay user и иметь responder-права. Подробнее: Shelving.

Канал Slack

Канал Slack#

Режим входящего вебхука#

Режим Bot API#

Создание приложения Slack#

Выбор транспорта интерактивных действий#

HTTP Request URL#

Поиск signing secret#

Socket Mode#

Поиск ID канала#

Настройка IncidentRelay#

Атрибуция пользователю#

Поведение сообщений#

Кнопка теста#

Устранение неполадок#

Slack возвращает invalid_auth#

Slack возвращает not_in_channel#

Сообщения отправляются, но кнопки не работают#

Действие Slack отклоняется как устаревшее#

Действие Slack отклоняется из-за несоответствия канала#

Сообщения не обновляются#

Замечания по безопасности#

Справочные материалы Slack#

У воркера Socket Mode нет соединений#

Журналирование воркера Slack#

Shelving#

Slack возвращает `invalid_auth`#

Slack возвращает `not_in_channel`#