sentry-bitrix24 0.3.0

Plugin for Sentry which allows sending notifications to Bitrix24 chat.

sentry-bitrix24

Плагин для self-hosted Sentry, который отправляет уведомления об ошибках в чат Bitrix24 через метод imbot.message.add.

Протестирован с Sentry 23.9.1.

Возможности

• Отправка уведомлений от имени чат-бота Bitrix24
• Отдельная настройка для каждого проекта Sentry — разные проекты могут слать в разные чаты
• Несколько чатов на один проект (по одному DIALOG_ID на строку)
• Настраиваемый шаблон сообщения с BB-кодами Bitrix24

Установка

1. Скопировать плагин в папку sentry

При сборке Docker-образа Sentry в контейнер попадает только содержимое папки sentry/ из репозитория self-hosted. Скопируйте весь репозиторий плагина (корень, где лежит setup.py) в эту папку:

# из корня репозитория self-hosted
cp -r /path/to/sentry-bitrix24 sentry/sentry_bitrix24

Итоговая структура:

self-hosted/
└── sentry/
    ├── Dockerfile
    ├── enhance-image.sh
    ├── sentry_bitrix24/      ← скопированный плагин
    │   ├── setup.py
    │   └── sentry_bitrix24/
    │       ├── __init__.py
    │       └── plugin.py
    └── ...

Важно: путь в pip install указывает на корень с setup.py, а не на plugin.py.

2. Добавить установку в enhance-image.sh

cp sentry/enhance-image.example.sh sentry/enhance-image.sh

В sentry/enhance-image.sh:

#!/bin/bash
set -euo pipefail

pip install /usr/src/sentry/sentry_bitrix24

3. Пересобрать образ и запустить Sentry

./install.sh
docker compose up -d

Проверка:

docker compose exec web pip show sentry-bitrix24

Установка без пересборки образа

Если плагин уже скопирован в sentry/sentry_bitrix24/ на хосте (папка смонтирована в контейнер как /etc/sentry/):

docker compose exec web pip install /etc/sentry/sentry_bitrix24
docker compose restart web worker post-process-forwarder-errors

После обновления кода плагина:

docker compose exec web pip install --force-reinstall /etc/sentry/sentry_bitrix24
docker compose restart web worker post-process-forwarder-errors

Установка из PyPI

Если пакет опубликован на pypi.org, в enhance-image.sh достаточно:

pip install sentry-bitrix24

Настройка Bitrix24

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

В Bitrix24: Разработчикам → Другое → Входящий вебхук.

Выдайте права «Создание и управление чат-ботами (imbot)».

Скопируйте базовый URL:

https://example.bitrix24.ru/rest/1/your-webhook-token/

2. Регистрация чат-бота

После регистрации бота Bitrix24 выдаёт:

Параметр	Поле в плагине	Пример
BOT_ID	Bot ID	123
CLIENT_ID (код бота)	Client ID	your-bot-client-id

3. Добавьте бота в чат

Бот должен быть участником чата. Для группового чата используйте chat{id}, например chat12345.

Проверка вебхука

Рабочий запрос (GET):

https://example.bitrix24.ru/rest/1/your-webhook-token/imbot.message.add.json?BOT_ID=123&CLIENT_ID=your-bot-client-id&DIALOG_ID=chat12345&MESSAGE=Привет!

Или POST (так отправляет плагин):

curl -X POST 'https://example.bitrix24.ru/rest/1/your-webhook-token/imbot.message.add' \
  -H 'Content-Type: application/json' \
  -d '{
    "BOT_ID": "123",
    "CLIENT_ID": "your-bot-client-id",
    "DIALOG_ID": "chat12345",
    "MESSAGE": "Тест из Sentry"
  }'

Настройка плагина в Sentry

Плагин настраивается отдельно для каждого проекта:

1. Откройте Settings нужного проекта.
2. Перейдите в Legacy Integrations.
3. Включите Bitrix24 Notifications.
4. На странице Configure plugin заполните поля:

Поле	Пример
Bitrix24 webhook URL	https://example.bitrix24.ru/rest/1/your-webhook-token/
Bot ID	123
Client ID	your-bot-client-id
Dialog IDs	chat12345
Message Template	(см. ниже)

Для другого проекта Sentry повторите шаги 1–4 с другим Dialog IDs.

Плейсхолдеры шаблона

Плейсхолдер	Описание
{project_name}	Название проекта
{url}	Ссылка на issue в Sentry
{title}	Заголовок issue
{message}	Текст ошибки
{culprit}	Culprit
{tag[level]}	Значение тега

Шаблон по умолчанию

[B][Sentry][/B] {project_name} {tag[level]}: [B]{title}[/B]
[CODE]{message}[/CODE]
[URL={url}]{url}[/URL]

Примечания

• Используется метод imbot.message.add (не imbot.v2), так как Bitrix24 выдаёт BOT_ID + CLIENT_ID, а не botToken.
• Один бот и один вебхук могут обслуживать все проекты — меняется только Dialog IDs в настройках каждого проекта.
• Плагин использует legacy plugin API Sentry. Для Sentry 23.9.1 это должно работать.

Лицензия

MIT