Зачем нужен бот в Nextcloud Talk
Когда в финансах или медицине требуют, чтобы алерты, события CI/CD и задачи Bitrix24 не покидали периметр организации, бот в Nextcloud Talk закрывает вопрос: данные не уходят во внешние мессенджеры. Webhook-based bots появились в Nextcloud 27.1 с Talk 17.1, capability называется bots-v1.
В команде IT For Prof мы развернули десятки таких интеграций и собрали тут практику: что важно при проектировании, как защитить вебхук, как пересылать события из Zabbix, GitLab и Bitrix24, и какие грабли вылезают в продакшене.
Архитектура: входящие и исходящие вебхуки
В Talk две модели интеграции. Исходящая — сервер шлёт POST на ваш endpoint при каждом событии в комнате; тело в формате Activity Streams 2.0. Входящая — бот пишет ответ через POST на OCS API. Capability bots-v1 мы всегда проверяем через capabilities API до раскатки: на изолированной сборке Talk 16 у клиента бот молча отказывался работать, и мы потеряли вечер на диагностику.
Talk не ждёт ответа от вебхука. Если сервис отвалится или ответит за десятки секунд — событие всё равно считается доставленным. Поэтому ставим nginx перед обработчиком, отвечаем 200 OK сразу после проверки подписи, а основную работу выносим в очередь. Иначе при всплеске сообщений упрётесь в воркеры и потеряете события.
Регистрация бота и проверка HMAC-SHA256
Боты добавляются только через CLI — веб-интерфейс эту операцию не поддерживает осознанно. Секрет генерируем через openssl rand -hex 32 и сразу кладём в Vault, sops или Kubernetes Secret. Засветить его в bash-history нельзя: кто получил секрет, тот шлёт сообщения от имени бота.
Каждый запрос приходит с заголовками X-Nextcloud-Talk-Random (64 символа) и X-Nextcloud-Talk-Signature (64-символьная hex-строка). Подпись считается как HMAC-SHA256(secret, RANDOM || body) над сырыми байтами тела. Сравнение — только constant-time: hash_equals в PHP, hmac.compare_digest в Python.
Любой бот без проверки подписи — открытый шлюз для записи в любую комнату, где он состоит. Один раз у заказчика забытый тестовый скрипт на CI-агенте неделю слал сообщения в боевые комнаты. Разбор занял день.
Дополнительно держим значение random в Redis с коротким TTL — это защита от повтора запроса.
Zabbix, GitLab и Bitrix24 в каналах Talk
Между внешней системой и Talk ставим тонкую прослойку на 30 строк (FastAPI или Express): она принимает payload и подписывает запрос секретом бота.
- Zabbix - Talk: медиатип Webhook в админке Zabbix шлёт subject, message, severity, host в адаптер. Адаптер форматирует Markdown и отправляет с правильной HMAC-подписью.
- GitLab - Talk: Project Webhooks, фильтрация по веткам в YAML. В дежурном чате — только failed pipelines на main, чтобы убрать шум.
- Bitrix24 - Talk: исходящий вебхук на событие OnTaskUpdate. У одного клиента при просрочке дедлайна задача попадает в личную беседу с ответственным — адаптер создаёт one-to-one room через API и кэширует token в Redis.
Эксплуатация: дубли, лимиты, отладка
В продакшене регулярно встречаем три класса проблем.
Дубли сообщений. Talk не гарантирует at-most-once: после 500 или таймаута событие переотправляется. Держим идемпотентность на стороне бота — Redis SETNX по object.id с TTL около часа закрывает 99% повторов в Jira, биллинг и SMS-шлюз.
Rate limits. Talk применяет лимиты на запись через bot API, пороги не задокументированы. При лавине алертов от двухсот хостов Zabbix эскалационный бот упёрся в лимит — часть сообщений в чат не дошла. Решение: склеивать однотипные алерты в одно сообщение с агрегацией (24 хоста кластера db-replica недоступны), а не слать по одному.
Поломка после обновления. Поле object.name для сообщений с вложениями было пустым из-за бага до Nextcloud 33 с Talk 23. Поля object.inReplyTo и actor.talkParticipantType появились только в Talk 21 — парсер не должен падать на их отсутствии.
Отладка. Первая команда при «бот не отвечает» — occ talk:bot:list: видны URL, привязанные комнаты и счётчик ошибок последних доставок. Дальше смотрим nextcloud.log с фильтром по приложению spreed. Чаще всего — истёкший сертификат на стороне бота или DNS-резолв из контейнера Nextcloud в закрытую сеть.
Флаг --feature event отключайте, если он не нужен: на инсталляции в восемь сотен пользователей события вошёл/вышел дают существенный фоновый трафик к боту.