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

Кратко

Входящие вебхуки позволяют внешним системам создавать заявки в платформе поддержки через HTTP-запрос. Это удобно для интеграции с системами мониторинга, внешними формами обратной связи, CRM и другими сервисами, которые должны автоматически создавать тикеты при определённых событиях. Это один из способов интеграции с платформой — общий обзор способов см. в руководстве Интеграция с Support по API.

Кто имеет доступ

Где найти

Настройки -- вкладка Триггеры автоматизации (#settings/automation) -- блок Входящие вебхуки. Под списком вебхуков показан адрес эндпоинта. Входящие вебхуки доступны на тарифах Starter и выше.

Как работает

Принцип работы

Каждый входящий вебхук имеет уникальный API-ключ. Внешняя система отправляет POST-запрос на публичный эндпоинт с этим ключом, передавая данные о заявке в формате JSON. Система создаёт тикет с переданными данными, дополняя недостающие поля значениями по умолчанию.

Публичный эндпоинт

Ключ передаётся только в заголовке X-Api-Key (query-параметр ?key= не поддерживается по соображениям безопасности).

POST https://support.tehprof.kz/api/webhook-in.php
X-Api-Key: {api_key}
Content-Type: application/json

Формат payload

{
  "subject": "Сервер database-01 недоступен",
  "description": "Мониторинг зафиксировал отсутствие ответа от сервера database-01 в течение 5 минут.",
  "client_name": "Иванов Артём",
  "client_email": "ivanov@company.kz",
  "client_phone": "+77001234567",
  "priority": "urgent",
  "category": "other"
}

Синхронизация компании и контакта (F513)

Внешняя система может передать компанию и контакт своего клиента — заявка автоматически привяжется к нужной компании. Сопоставление идемпотентно по стабильным внешним ключам (канон Zendesk/Intercom: external_id). Как эти же ключи используются при поиске контакта по обращению — в статье Контакты клиента.

Порядок обработки: проверка external_ref (если заявка уже есть — возврат её) → найти/создать компанию по company_external_id/company_bin → найти/создать контакт по contact_external_id/телефону/почте → привязать контакт к компании → создать заявку с этой компанией. Все ключи изолированы по тенанту.

Как формируется имя контакта и название компании

Система показывает ровно те значения, которые вы прислали в запросе — она ничего не «подтягивает» из посторонних источников и не угадывает.

• Имя контакта = поле client_name. Если контакт с такой личностью (по contact_external_id, телефону или почте) уже существовал — имя не перезаписывается, остаётся первое присланное значение. Это сделано, чтобы случайный пустой/служебный запрос не затирал уже корректное имя.
• Название компании = поле company_name. Используется только при создании новой компании. Если компания уже найдена по company_external_id/company_bin — её название присланным company_name не меняется.
• Заранее заводить контакт или компанию не нужно — они создаются автоматически при первой заявке.

Типичная ошибка. Если ваш бэкенд шлёт в client_name имя служебного админ-аккаунта (например, «Администратор» или «Client»), именно оно и попадёт в заявку. Шлите реальное ФИО конкретного пользователя, который подаёт заявку.

Решение проблем

Кроме subject, все поля опциональны. Если категория, приоритет или источник не переданы, используются значения по умолчанию, заданные в настройках вебхука. Переданные email и телефон дополнительно записываются в заявку системным сообщением.

Значения по умолчанию

При создании входящего вебхука администратор задаёт значения по умолчанию для полей, которые внешняя система может не передавать:

• Услуга по умолчанию -- категория заявки
• Приоритет по умолчанию -- по умолчанию «Обычный» (normal)
• Источник по умолчанию -- по умолчанию api

Переданные в запросе значения имеют приоритет над значениями по умолчанию.

Ответ API

Успешное создание (HTTP 201):

{
  "ok": true,
  "ticket_id": 4522,
  "status": "new",
  "company_id": 1611,
  "contact_id": 9270
}

Идемпотентный повтор по external_ref (HTTP 200):

{
  "ok": true,
  "ticket_id": 4522,
  "status": "new",
  "deduplicated": true
}

Ошибка авторизации (HTTP 401):

{
  "ok": false,
  "error": "Invalid or inactive API key"
}

Ошибка валидации (HTTP 400):

{
  "ok": false,
  "error": "subject is required"
}

Rate limiting

Действует ограничение 60 запросов в час с одного IP-адреса. При превышении возвращается HTTP 429 (Too Many Requests).

Настройка

Создание входящего вебхука

1. Перейдите в Настройки -- Триггеры автоматизации, блок «Входящие вебхуки»
2. Нажмите «Добавить входящий вебхук»
3. Укажите название (например, «Мониторинг Zabbix» или «Форма на сайте»)
4. Задайте значения по умолчанию: услуга, приоритет, источник
5. Сохраните -- API-ключ будет сгенерирован автоматически

Копирование ключа

После создания откроется окно с API-ключом, адресом эндпоинта и примером запроса curl (кнопки «Копировать ключ» и «Копировать curl»). Ключ показывается только один раз: в базе он хранится в захешированном виде, позже в списке виден только его начальный фрагмент. Настройте внешнюю систему на отправку POST-запросов на эндпоинт с ключом в заголовке X-Api-Key.

Примеры использования

Мониторинг (Zabbix, Grafana):

При срабатывании алерта система мониторинга отправляет запрос с описанием проблемы. Приоритет определяется уровнем алерта.

Форма на внешнем сайте:

HTML-форма отправляет данные через JavaScript на эндпоинт вебхука. Подходит для сайтов, где нельзя встроить виджет.

CI/CD pipeline:

При падении деплоя или тестов система автоматически создаёт тикет на команду поддержки.

IoT устройства:

Датчики отправляют данные при отклонении от нормы, создавая заявку на обслуживание.

Частые вопросы

Можно ли обновлять существующий тикет через входящий вебхук?

Нет, входящие вебхуки только создают новые заявки. Для защиты от дублей при повторной отправке передавайте external_ref — запрос с уже использованным ключом вернёт ранее созданную заявку (deduplicated: true), а не создаст новую.

Как синхронизировать компании и контакты клиентов?

Передавайте company_external_id (ваш стабильный ID компании) и contact_external_id (ваш ID пользователя) в каждом запросе создания заявки. Компания и контакт находятся или создаются на лету и связываются между собой — заявка автоматически привязывается к компании. Отдельная массовая загрузка справочника не требуется: данные поддерживаются в актуальном состоянии по мере поступления заявок. Входящие вебхуки — лишь одна из форм автоматизации приёма заявок; более широкий обзор — в статье Автоматизация поддержки клиентов.

Как защитить вебхук от злоупотреблений?

API-ключ уже обеспечивает базовую защиту. Дополнительно действует rate limiting. Для критичных интеграций рекомендуется ограничить доступ по IP на уровне firewall.

Что происходит при передаче несуществующей категории?

Значение category сохраняется в заявке как передано, без проверки по справочнику услуг. Значение по умолчанию подставляется только когда category не передано или пустое.

Можно ли передавать вложения?

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

Связанные статьи

• Исходящие вебхуки -- уведомление внешних систем
• Триггеры автоматизации -- автоматические действия при событиях
• Создание заявки (клиент) -- другие способы создания заявок
• Встраивание виджета на сайт -- альтернатива для внешних форм