Боты и вебхуки в Nextcloud Talk: автоматизация уведомлений

nextcloud talk бот: что важно знать перед принятием решения.

Разбираем контекст, ключевые критерии, риски и практические шаги без привязки к шаблонным сценариям.

Когда мы проектируем nextcloud talk бот для клиента, первое, что объясняем — в Talk две принципиально разные модели интеграции: исходящие вебхуки от сервера к боту и входящие вызовы от бота обратно через OCS API. Webhook-based bots появились в релизе Nextcloud 27.1 с Talk 17.1, до этого внешние интеграции собирались через Matterbridge или костыли поверх REST.

Исходящая часть: сервер Nextcloud при каждом событии в комнате (новое сообщение, реакция, добавление участника) отправляет HTTP POST на ваш endpoint. Тело — JSON в формате Activity Streams 2.0 Vocabulary. Это означает, что любая библиотека, умеющая разбирать ActivityPub-структуры, читает события Talk без отдельного адаптера.

Входящая часть: ваш бот пишет ответ в чат через POST на `/ocs/v2.php/apps/spreed/api/v1/bot/{token}/message`. Базовый endpoint требует capability `bots-v1` — мы всегда проверяем её наличие через `/ocs/v2.php/cloud/capabilities` перед раскаткой в продакшен, потому что у одного клиента на изолированной сборке Talk 16 интеграция тихо отказывалась работать, и мы потеряли вечер на диагностику.

Ключевая архитектурная развилка — синхронность. Talk не ждёт ответа от вебхука: если ваш сервис отвалится или ответит за десятки секунд, событие всё равно считается доставленным. Это меняет дизайн обработчика: ставим nginx перед FastAPI/PHP-FPM, отвечаем 200 OK сразу после валидации подписи, основную обработку выносим в очередь (RQ, Celery, Sidekiq — что есть в стеке). Иначе при всплеске сообщений в активной комнате упрётесь в воркеры и начнёте терять события.

Ещё одна особенность — направление трафика. Talk-сервер должен достучаться до вашего вебхука по HTTPS. На наших проектах в закрытых корпоративных сетях, где Nextcloud стоит во внутреннем сегменте, мы поднимаем бота рядом — в том же VLAN или Docker-сети, чтобы не тянуть трафик наружу. Если бот должен жить во внешнем облаке, потребуется выходной NAT и валидный сертификат на стороне бота: самоподписанные Talk отвергает.

Третья модель — Nextcloud-приложения как боты. Они регистрируются изнутри Nextcloud, шарят БД и сессии, но требуют PHP-кода в составе приложения. Эта схема даёт больше возможностей (доступ к Files, Calendar, Activity), но привязывает вас к версии Nextcloud — мы используем её только когда логика бота тесно завязана на внутренние данные инстанса, а во всех остальных случаях идём по классической схеме вебхуков.

Боты добавляются только через CLI (occ): для безопасности веб-интерфейс эту операцию не поддерживает. Это сделано осознанно — администратор, имеющий доступ к OCC, заведомо доверенное лицо, тогда как UI могут получить пользователи с правами admin без shell-доступа. У нас был случай, когда заказчик требовал «кнопочку в админке» — пришлось писать обёртку: systemd-юнит с sudo на конкретную occ-команду и тонкая веб-форма поверх, чтобы не давать shell.

Базовая последовательность установки бота на сервере выглядит так:

Первый аргумент — отображаемое имя бота в чате. Второй — shared secret, который Talk использует для подписи HMAC-SHA256. Мы генерируем его через `openssl rand -hex 32` (32 байта = 64 hex-символа) и сразу кладём в секрет-менеджер: Vault, sops, Kubernetes Secret. Засветить секрет в bash-history категорически нельзя — кто получил секрет, тот может слать сообщения от имени бота и подделывать подписи входящих.

Третий аргумент — URL вебхука. Talk проверяет схему (только HTTPS) и DNS при установке, но тестовый POST не делает — реальную проверку увидите только при первом событии в комнате, куда добавите бота. Четвёртый — описание, оно видно в карточке бота при добавлении к комнате. Флаг `–feature` управляет, какие события бот получает: `webhook` — все события, `response` — разрешение писать в чат, `event` — служебные события (присоединение/выход).

После установки бот находится в списке доступных, но ни к одной комнате не привязан. Добавление в комнату — отдельный шаг через `talk:bot:setup`, и его удобно автоматизировать: при заведении новой команды в Talk скрипт прогоняет список «дефолтных» ботов и добавляет их в нужные комнаты по таблице соответствия. У одного заказчика мы держим эту таблицу прямо в etcd, чтобы при разворачивании нового окружения боты автоматически подтягивались.

Каждый запрос от Talk к вашему боту приходит с двумя заголовками: `HTTP_X_NEXTCLOUD_TALK_RANDOM` — 64-символьная alphanumeric строка с допустимым символом `+`, и `HTTP_X_NEXTCLOUD_TALK_SIGNATURE` — 64-символьная hex-строка. Подпись считается как `HMAC-SHA256(secret, RANDOM || body)`, где `||` — конкатенация без разделителя.

Проверка на PHP — буквально две строки, как даёт официальная документация Nextcloud Talk Bots API:

`hash_equals` обязательно — простое `===` уязвимо к timing-атакам, и хотя на практике у Talk это вряд ли реалистично эксплуатируется, мы не делаем исключений: где есть HMAC, там есть constant-time сравнение. На Python используется `hmac.compare_digest`, на Go — `subtle.ConstantTimeCompare`.

Чтение тела через `file_get_contents(‘php://input’)` критично — нельзя пересобирать тело из `$_POST` или JSON-декодером, потому что подпись считается над байтами сырого payload. Минимальный пробел или переупорядочивание ключей — другой HMAC. По той же причине в Node.js приходится отключать автоматический body-parser и снимать body через `req.on(‘data’)`, иначе подпись не сойдётся ни при каких настройках.

Не делайте проверку подписи опциональной — мы сталкивались с конфигурацией, когда разработчик «временно» закомментировал валидацию для отладки, выкатил в прод, и через неделю бот начал писать в комнаты сообщения, которых Talk не отправлял. Источник нашли — старый тестовый скрипт, оставшийся на CI-агенте, который дёргал endpoint напрямую без секрета. Расследование заняло день. Любой nextcloud talk бот без проверки подписи — открытый шлюз для записи в любую комнату, где он состоит.

Дополнительный слой — replay-защита. Talk не шлёт timestamp в заголовках, поэтому теоретически перехваченный запрос можно проиграть. Мы храним `random` в Redis с коротким TTL и отклоняем повтор: значение в 64 символа уникально для каждого вызова, коллизий не бывает. Это особенно важно, если бот выполняет действия с побочными эффектами — создаёт тикет в Jira, шлёт SMS, дёргает API биллинга.

Подпись не покрывает заголовки, кроме `RANDOM`. URL, IP-адрес источника, `User-Agent` и `BACKEND` (URI исходного Nextcloud) — всё это вспомогательная информация, на которую при авторизации полагаться нельзя. Единственный источник истины — secret и HMAC, всё остальное справочно.

Зачем городить nextcloud talk бот, если есть email и Telegram? Главный аргумент — данные не уходят за периметр организации. У клиентов из финансов и медицины это не «приятно иметь», а требование службы информационной безопасности. На наших проектах мы вытащили в Talk алерты Zabbix, события CI/CD из GitLab и пуш-уведомления Bitrix24, не привлекая внешние мессенджеры.

Zabbix → Talk собирается через медиатип «Webhook» в админке Zabbix. В качестве endpoint указываете URL вашего адаптера, в параметры — `subject`, `message`, `severity`, `host`. Скрипт медиатипа на JavaScript внутри Zabbix формирует POST. Сложность одна: Zabbix-вебхук работает по схеме »от Zabbix к произвольному URL«, а Talk требует, чтобы POST приходил подписанным от бота. Поэтому посередине ставим тонкую прослойку — FastAPI или Express на 30 строк, которая получает Zabbix-payload, форматирует Markdown (Talk поддерживает `text/markdown` через mediaType) и отправляет в Talk с правильной HMAC-подписью, используя secret бота.

GitLab проще: в Project → Webhooks указываете URL адаптера и события (Push, Pipeline, Merge Request). Адаптер берёт payload GitLab, фильтрует по веткам/проектам и шлёт в Talk. Мы держим маршрутизацию в YAML: для каждой комнаты Talk прописан список GitLab-проектов и фильтры (например, отправлять только failed pipelines на main). Это убирает шум — никто не хочет видеть в дежурном чате сотни уведомлений в день о MR-комментариях.

Bitrix24 интегрируется через исходящие вебхуки. Событие `OnTaskUpdate` отправляет POST на ваш endpoint, адаптер форматирует и шлёт в комнату менеджеров. На одном проекте у клиента было требование: при просрочке дедлайна задача должна попадать не в общий чат, а в индивидуальную беседу с ответственным. Адаптер дёргает Talk API `/ocs/v2.php/apps/spreed/api/v4/room` для создания one-to-one беседы, если её ещё нет, кэширует token в Redis и шлёт сообщение туда.

Пример минимального адаптера на bash для отправки в Talk:

Этот шаблон легко переиспользуется в любых системах, которые умеют дёргать shell-команду на алерт — от cron до systemd-сервисов мониторинга.

Бот, который только пишет — это RSS-лента. Бот, который читает реакции и команды — рабочий инструмент эскалации. Talk шлёт боту события не только о новых сообщениях, но и о добавлении/удалении реакций, и эти события приходят на тот же вебхук, но с другим `type` в payload.

Типичный сценарий, который мы делали для дежурной смены: алерт Zabbix приходит в комнату, бот подписывает его эмодзи 🚨. Дежурный ставит реакцию 👀 — бот фиксирует «взято в работу» и в DM-беседу старшему инженеру не пишет. Если за условные несколько минут реакции нет — эскалация: DM старшему и параллельно второму уровню по списку. Реакция ✅ закрывает инцидент и пишет post-mortem-заглушку в Confluence через API.

Технически слушаем `type: Create` в JSON для сообщений и проверяем `object.type`: для реакций он отличается по Activity Streams. Поле `object.id` содержит ID родительского сообщения — связываем реакцию с алертом. Поле `object.inReplyTo`, которое появилось в Nextcloud Talk 21, позволяет дотянуться до контекста цитируемого сообщения. Поле `actor.id` даёт нам отправителя в формате `users/<uid>`, по нему понимаем кто и из какой смены. Поле `actor.talkParticipantType`, добавленное в Talk 21, помогает отличать модераторов от обычных участников — например, закрывать инцидент могут только модераторы канала.

Slash-команды реализуются на уровне бота: вы парсите `object.content.message`, если строка начинается с `/`, разбираете команду и параметры. Talk не имеет встроенного механизма автодополнения slash-команд для внешних ботов — это отличает его от Slack и Mattermost. Мы обходим тем, что бот на команду `/help` присылает список доступных команд в чат, пользователь видит и копирует. Альтернатива — закрепить сообщение со списком команд при добавлении бота в комнату.

Не пытайтесь делать сложные диалоговые сценарии с состоянием через одни реакции — мы пробовали и наступали на грабли: пользователь снимает реакцию, бот считает это отменой действия, а человек просто перепутал кнопку и тут же поставил правильную. Состояние держите в БД на стороне бота, реакции используйте как триггеры, а не как полноценную state-машину.

Полезный поворот — отвечать на сообщение реакцией от имени бота, без текста. Тогда лента чата не засоряется ботскими «принято». Endpoint `/ocs/v2.php/apps/spreed/api/v1/reaction/{token}/{messageId}` принимает POST с эмодзи. Дежурные оценили — алерт получает 🟡 «в обработке», транзитный статус и 🟢 «закрыто», история комнаты остаётся читаемой при разборе инцидента.

После запуска nextcloud talk бот в продакшене мы регулярно встречаем три класса проблем: всплески нагрузки, дубли сообщений и тихая поломка после обновлений Nextcloud. Расскажем, какие признаки и что с этим делать.

Дубли сообщений. Talk не имеет строгого at-most-once механизма доставки вебхуков. Если ваш бот ответил 500 или таймаутом, событие может быть переотправлено в зависимости от настроек сервера. На стороне бота держите идемпотентность: ключ — `object.id` сообщения, и при повторе того же ID просто игнорируйте обработку. Мы используем Redis `SETNX` с TTL около часа: первый раз ключ создаётся, повтор отбрасывается. Это закрывает 99% проблем с дубликатами уведомлений во внешние системы (Jira, биллинг, SMS-шлюз).

Rate limits. Talk применяет rate limiting на запись через bot API, конкретные пороги зависят от конфигурации сервера и не задокументированы детально. У одного клиента бот эскалации при массовом инциденте (сетевой сбой, лавина алертов от двухсот хостов Zabbix) упёрся в лимит, и часть алертов в чат не попала. Решение — на стороне адаптера склеивать однотипные алерты в одно сообщение с агрегацией («24 хоста в кластере db-replica недоступны»), а не слать по одному. Это и читабельнее, и не выжигает лимиты записи.

Поломка после обновления. Поле `object.name` для сообщений с вложениями было пустой строкой из-за бага вплоть до Nextcloud 33 с Talk 23. Если ваш бот валит обработку на пустом `name`, после апгрейда поведение изменится — пишите код устойчивым к обоим вариантам. Аналогично, поля `object.inReplyTo` и `actor.talkParticipantType` появились только в Talk 21 — на более старых версиях их нет, парсер не должен падать на отсутствии `name`.

Отладка. Первая команда, которую мы запускаем при «бот не отвечает»:

Она показывает все установленные боты, их URL, какие комнаты привязаны, и счётчик ошибок последних доставок. Если счётчик растёт — Talk не может достучаться до вашего endpoint. Дальше смотрим логи Nextcloud (`/var/www/nextcloud/data/nextcloud.log`) с фильтром по приложению `spreed` — там видны код ответа от вашего бота и тело ошибки. Часто проблема прозаична: истёкший сертификат на стороне бота или DNS-резолв из контейнера Nextcloud в закрытую сеть.

Не оставляйте `feature=event` включённым, если он вам не нужен — на больших инсталляциях события «вошёл/вышел» и «прочитано» генерируют значительный фоновый трафик к боту. У клиенту с восьмью сотнями пользователей и активным онбордингом мы выключили event-фичу трёх ботов из рех ботов из трёх рабочих окружений, и нагрузка от этого ощутимо упала.

Ответы на часто задаваемые вопросы по теме статьи.

Константин Тютюнник — ведущий инженер IT For Prof. Специализируется на архитектуре частных облачных решений и интеграции сервисов совместной работы. Имеет более 10 лет опыта в администрировании высоконагруженных Linux-систем и разработке безопасных API-взаимодействий для enterprise-сегмента.