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

Кратко

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

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

Роль	Просмотр	Создание	Редактирование	Удаление
Администратор	да	да	да	да
Руководитель	да	да	да	да
Оператор	нет	нет	нет	нет
Сотрудник клиента	нет	нет	нет	нет

Где найти

Настройки -- Автоматизация -- Входящие вебхуки. Раздел доступен из бокового меню административной панели.

Как работает

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

Каждый входящий вебхук имеет уникальный 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"
}

Поле	Тип	Обязательное	Описание
subject	string	да	Тема заявки
description	string	нет	Описание проблемы (если пусто -- = subject)
client_name	string	нет	Имя контактного лица
client_email	string	нет	Email контакта
client_phone	string	нет	Телефон контакта (нормализуется к +7XXXXXXXXXX)
priority	string	нет	Приоритет: normal, urgent, estimate
category	string	нет	Категория: crm, telephony, whatsapp, tasks, automation, setup, bugfix, other
custom_fields	object	нет	Произвольные поля → в метаданные заявки

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

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

Поле	Тип	Описание
company_external_id	string	Рекомендуемый ключ компании — стабильный ID компании в вашей системе. Поиск/создание идемпотентны по нему.
company_bin	string	БИН/ИИН (12 цифр) — вторичный ключ компании (для юрлиц без вашего ID).
company_name	string	Название компании. Используется при создании новой.
contact_external_id	string	Рекомендуемый ключ контакта — стабильный ID пользователя. Сильнейший идентификатор (приоритетнее телефона/почты).
external_ref	string	Ключ идемпотентности заявки. Повторный запрос с тем же `external_ref` не создаёт дубль — возвращается ранее созданная заявка (`deduplicated: true`).

Порядок обработки: проверка 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»), именно оно и попадёт в заявку. Шлите реальное ФИО конкретного пользователя, который подаёт заявку.

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

Симптом	Причина	Что делать
В заявке показывается «Администратор» / «Client» / не то имя	В `client_name` ушло имя служебного аккаунта вашей системы	Слать реальное ФИО пользователя в `client_name`
Имя контакта не обновляется, хотя прислал новое	У существующего контакта имя не перезаписывается	Поправить имя вручную в карточке контакта, либо использовать разные `contact_external_id` для разных людей
Компания не привязывается к заявке	Используется другой эндпоинт (серверный мост `issue_client_token` / операторский `create_ticket`) — он поля компании не принимает	Слать заявку через `webhook-in.php` с `company_external_id` / `company_bin`
Создаётся дубль заявки при повторе	Не передан `external_ref`	Передавать стабильный `external_ref` — повтор вернёт ту же заявку (`deduplicated: true`)
В наименовании лишний префикс (например «TIME-…»)	Это значение из вашего payload (тема/код заявки вашей системы)	Support префиксов к теме не добавляет — проверьте, что кладёте в `subject`

Все поля опциональны. Если поле не передано, используется значение по умолчанию, заданное в настройках вебхука.

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

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

Статус -- по умолчанию "new"
Приоритет -- по умолчанию "medium"
Категория -- настраивается при создании вебхука

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

Ответ 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).

Настройка

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

Перейдите в Настройки -- Автоматизация -- Входящие вебхуки

Нажмите "Создать вебхук"

Укажите название (например, "Мониторинг Zabbix" или "Форма на сайте")

Задайте значения по умолчанию: статус, приоритет, категория

Сохраните -- API-ключ будет сгенерирован автоматически

Копирование URL

После создания вебхука скопируйте полный URL (включая ключ) и настройте внешнюю систему на отправку POST-запросов по этому адресу.

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

Мониторинг (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.

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

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

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

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

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

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

Не нашли ответ? Найдите другую статью или напишите в поддержку.