Webhooks и API в ServiceDesk: интеграция с Битрикс24, amoCRM и не только

Зачем интегрировать ServiceDesk

ServiceDesk обрабатывает заявки. Но информация о клиентах живёт в CRM, заявки на закупки идут в ERP, маркетинговые рассылки запускаются в отдельной системе. Без интеграций оператор каждый день копирует данные между 5 системами вручную — это съедает 15-30% рабочего времени.

Типовые направления интеграций:

• CRM (Битрикс24, amoCRM, RetailCRM) — синхронизация контактов и истории взаимодействий;
• ERP / 1С — заявки на закупки, инвентарь оборудования;
• Мессенджеры (Telegram, корпоративные чаты) — уведомления операторов и клиентов;
• BI / Analytics (Yandex DataLens, Power BI, Metabase) — глубокая аналитика;
• Внутренние сервисы — Wiki, файловое хранилище, мониторинг.

REST API: что обычно есть в современном ServiceDesk

Минимум для интеграции — REST API с покрытием базовых сущностей:

• Tickets: GET list, GET single, POST create, PUT update, DELETE;
• Comments: POST к тикету, GET список;
• Users: GET list (для синхронизации с AD/CRM);
• Services / Catalog: GET list (для отображения каталога во внешнем UI);
• Reports / Search: запросы с фильтрами.

Современный API использует:

• OpenAPI 3.1 для документации — даёт автогенерацию SDK;
• Bearer tokens для аутентификации (Authorization: Bearer ABC...);
• Rate limiting per-token (100-1000 запросов/мин);
• Scopes на токенах (read-only / read-write / admin);
• Pagination с limit+offset или cursor;
• Идемпотентность для POST через Idempotency-Key header.

Outgoing webhooks (события из ServiceDesk наружу)

API — pull-модель (ты спрашиваешь систему). Webhooks — push: система сама сообщает о событиях. Это правильная архитектура для реал-тайма.

Типовые события:

• ticket.created — создалась заявка;
• ticket.updated — изменён статус/приоритет/исполнитель;
• ticket.commented — новый комментарий;
• ticket.closed — закрыта;
• ticket.sla_breached — нарушен SLA;
• user.created — добавлен пользователь.

Современная реализация — outbox pattern: события сначала записываются в БД, затем фоновый воркер доставляет их. Это гарантирует доставку даже при падении внешней системы:

1. В транзакции с изменением тикета — INSERT в outbox-таблицу;
2. Воркер раз в 30 сек берёт несохранённые события;
3. POST на endpoint клиента с HMAC-подписью в header;
4. Если 2xx — помечаем delivered;
5. Если ошибка — exponential backoff (30s, 5m, 30m, 4h, 24h), max 5 попыток;
6. Через ITSM-UI клиент может redeliver вручную или удалить.

Безопасность: HMAC, токены, ретраи

HMAC-подпись

Каждый webhook-POST содержит header X-Tiqqet-Signature: sha256=.... Клиент должен пересчитать HMAC-SHA256 от body с известным secret и сравнить. Если не совпадает — отвергнуть. Это защищает от подделки запросов.

Токены API

• Хранить хеш токена в БД (bcrypt), не plain-text — на случай leak'а БД;
• Срок жизни токена — по умолчанию 1 год, опционально без срока (но не рекомендуется);
• Логирование создания/использования/отзыва — в audit log.

Ретраи и идемпотентность

Webhook-получатели обязаны обрабатывать идемпотентно — событие может прийти несколько раз. Используйте уникальный ID события (`X-Tiqqet-Event-Id`) для дедупликации.

Реальные сценарии интеграции

1. Битрикс24 → ServiceDesk

Менеджер в Битрикс24 создаёт сделку с тегом «нужна техподдержка» → webhook → создаётся заявка в TIQQET с привязкой к клиенту → оператор разбирает → comment в заявке → webhook обратно в Битрикс24 → история в карточке сделки.

2. ServiceDesk → Telegram (отдельный канал)

Заявка с приоритетом CRITICAL → webhook → бот в Telegram → постинг в группу «Дежурные» с кнопкой «Принять». Без необходимости проверять почту/UI.

3. Заявка → закупка в 1С

Шаблон «Заявка на новое оборудование» → одобрение → webhook в 1С:Управление торговлей → создаётся документ «Закупка» с предзаполненными полями.

4. Мониторинг → ServiceDesk

Zabbix/Prometheus детектирует проблему → alertmanager → webhook на API ServiceDesk → автоматически создаётся incident-тикет с описанием. Дежурный оператор получает push, начинает разбор.

Подводные камни

• Webhook-receiver падает → не блокировать ServiceDesk. Использовать outbox+retry, не synchronous calls;
• Webhook-loop — событие из системы A создаёт событие в B, которое создаёт событие в A, и так бесконечно. Помечать события «source» чтобы не зацикливать;
• Доступ через интернет — receiver должен быть публично доступен. Альтернатива: VPN-туннель или event bus с pull-моделью;
• Размер payload — webhook должен быть лёгким (несколько КБ). Большие документы — давать ссылку, не отправлять целиком;
• Версионирование — поля webhook'a меняются со временем. Включайте в header версию (X-Tiqqet-Webhook-Version: v1).