Webhooks (вебхуки) предназначены для уведомления сторонних приложений о событиях, произошедших в CRM "Мой Класс". С помощью них вы можете осуществлять действия в других сервисах и приложениях, например, отправлять сообщения после получения платежей в "Мой Класс" или создания учеников, создавать лиды в другой системе после появления заявок в "Мой Класс", и т.д.
Если вам нужно осуществлять действия в нашей CRM по событиям в другом сервисе, например, создавать у нас контакт, если вы получили заявку через стороннюю форму, то вам нужны не вебхуки, а API.
Для работы с вебхуками нужно настроить их прием в вашем приложении, а также настроить в "Мой Класс" подписку, где выбрать, какие события отправлять в приложение.
Создание webhooks
Перейдите в раздел CRM "Мой Класс" "Настройки - API и webhooks". Если у вас этот раздел скрыт, нажмите на "Еще".
Во вкладке "Webhooks" нажмите "+ Webhook".
В открывшемся окне укажите название вебхука (для удобства), а также адрес сервера, на который вам нужно их отправлять. Как правило, адрес вы берете из того сервиса или приложения, в котором настраиваете ваши действия по вебхукам от нашей системы.
ВАЖНО! Обратите внимание, что никакой дополнительной авторизации при отправке вебхуков нет, поэтому рекомендуется создавать адреса, которые сложно подобрать, например, https://website.com/hooks/4e0bcaa6-e4fa-4c50-bc7c-c09857788701
Укажите филиалы ученика или программы/группы его записи, чтобы конкретизировать вебхук. Это необязательные параметры, можете оставить их не указанными, тогда вебхук будет срабатывать на действия в любом филиале или группе.
Определите события, которые вам необходимы в вебхуке.
Можно создать любое количество вебхуков и настроить таким образом любое количество подписок на события в нашей CRM. И в каждом вебхуке определить свои события.
Сохраните вебхук.
Готово.
Отправка Webhooks
Вебхук отправляется сразу после наступления события, однако в некоторых случаях (при большой нагрузке) возможны задержки в отправке.
Вебхук считается отправленным, если сервер вернул код 2хх (200, 201, 203 и т.д.). Если сервер вернул другой код или не ответил в течение 5 секунд, то через 1 минуту производится повторная попытка. Всего по каждому событию делается максимум 5 попыток с интервалом в 1 минуту.
Если сервер не принял 50 запросов подряд, то подписка переводится в статус "отключена из-за ошибок", и вебхуки на нее не отправляются. При этом вы можете снова включить подписку в CRM.
Структура Webhooks
ВАЖНО! Если вам не хватает данных, которые приходят в самом вебхуке, используйте их в связке с API. Например, в хуке приходит id занятия и некоторые данные - при необходимости можно запрашивать по API дополнительные данные занятия по его id.
События отправляются на указанный в настройках адрес методом POST, данные отправляются в формате JSON.
Данные имеют следующую структуру:
{
"companyId": <ID компании, в которой произошло событие>,
"event": <код события>,
"object": <объект, инициировавший событие>,
"time": <отметка времени UNIX, указывающая, когда было отправлено уведомление о событии>,
"changedFields": <массив, содержащий в себе список измененных полей сущности>,
"init": <объект, который описывает, откуда и кем было инициировано событие>
}
Поле event
Содержит код события, которое произошло.
Доступны следующие события:
-
user_new - Ученик создан
-
user_changed - Информация об ученике изменилась
-
user_changed_state - Статус ученика изменился
-
user_birthday - Ученик отмечает день рождения
-
join_new - Создана запись в группу
-
join_changed - Информация о записи в группу изменилась
-
join_changed_state - Статус записи в группу изменился
-
class_changed - Информация о группе изменилась
-
class_start_days - Старт группы менее чем через 7 дней (отправляется раз в сутки)
-
class_start_hours - Старт группы менее чем через 6 часов (отправляется раз в час)
-
lesson_changed - Информация о занятии изменилась
-
lesson_start_days - Занятие начинается менее чем через 7 дней (отправляется раз в сутки)
-
lesson_start_hours - Занятие начинается через 6 часов (отправляется раз в час)
- payment_new - Принят платеж
-
sub_lesson_in_debt - Занятие для записи проведено “в долг”
-
lesson_record_new - Создана запись на занятие
-
lesson_record_changed - Информация о записи на занятие изменилась
- lesson_record_deleted - Запись на занятие удалена
-
sub_days_next_payment - Осталось менее 5 дней до внесения очередного платежа/долга по абонементу
-
sub_lessons_left - В абонементе осталось менее 5 посещений
-
sub_end_days - Абонемент заканчивается менее чем через 5 дней
- user_consecutive_visit_missed_2 - Ученик имеет два пропуска подряд без уважительной причины
-
lesson_mark_set - Проставлена оценка
-
lesson_mark_deleted - Оценка удалена
-
lesson_task_new - Задание создано
-
lesson_task_changed - Задание изменено
Поле object
Содержит объект, к которому относится событие.
Объект пользователя
-
userId (integer) - ID ученика
-
filials (array[integer]) - ID филиалов ученика
-
attributes (array[object]) - Дополнительные атрибуты ученика
-
name (string) - Полное имя ученика
-
balans (integer) - Баланс ученика
-
email (string) - Email ученика
-
createdAt (string) - Дата создания ученика
-
statusId (integer) - ID статуса ученика
-
advSourceId (integer) - ID информационного источника (откуда ученик узнал о компании)
-
responsibleId (integer) - ID ответственного менеджера
-
statusReasonId (integer) - ID причины смены статуса ученика
-
createSourceId (integer) - ID источника создания ученика
-
prevStatusId (integer) - ID предыдущего статуса ученика
-
prevStatusReasonId (integer) - ID причины смены предыдущего статуса ученика
-
phone (string) - Номер телефона ученика
Используется в событиях: user_new, user_changed, user_changed_state, user_birthday.
Объект записи в группу
-
joinId (integer) - ID заявки
-
price (integer) - Цена (для групп с разовой оплатой)
-
userId (integer) - ID ученика
-
classId (integer) - ID группы
-
comment (string) - Комментарий
-
autoJoin (boolean) - Автоматически записывать в статусе “Учится” на все занятия в группе
-
managerId (integer) - ID ответственного сотрудника
-
remindSum (integer) - Сумма долга к оплате
-
createdAt (string) - Дата создания
-
statusId (integer) - ID статуса заявки
-
advSourceId (integer) - ID информационного источника (откуда ученик узнал о компании)
-
prevStatusId (integer) - ID предыдущего статуса заявки
-
createSourceId (integer) - ID источника создания
-
statusChangeReasonId (integer) - ID причины смены статуса
-
prevStatusChangeReasonId (integer) - ID причины смены предыдущего статуса
-
remindDate (string) - Срок оплаты долга
-
stats (object) - Статистика по записи
Используется в событиях: join_new, join_changed, join_changed_state.
Объект группы
-
classId (integer) - ID группы
-
name (string) - Название
-
color (string) - Цвет
-
price (integer) - Цена
-
comment (string) - Комментарий
-
statusId (integer) - ID статуса
-
courseId (integer) - ID программы
-
payPass (boolean) - Списывать посещения из абонемента за пропуски без уваж. причины
-
showDates (boolean) - Отобажение даты начала у названия группы
-
maxStudents (integer) - Максимальное количество студентов
-
filialId (integer) - ID филиала
-
priceComment (string) - Комментарий к цене
-
priceForWidget (string) - Цена для виджетов
-
createdAt (string) - Дата создания
-
payType (string) - Способ оплаты за обучение. full - разово, lessons - за занятия
-
beginDate (string) - Старт занятий
Используется в событиях: class_changed, class_start_days, class_start_hours.
Объект занятия
-
lessonId (integer) - ID занятия
-
topic (string) - Тема занятия
-
endTime (string) - Время окончания занятия
-
classId (integer) - ID группы
-
status (integer) - Статус
-
createdAt (string) - Дата создания
-
beginTime (string) - Время начала
-
description (string) - Описание занятия
-
filialId (integer) - ID филиала
-
roomId (integer) - ID аудитории
-
date (string) - Дата начала занятия
-
params (object) - Параметры занятия, в объекте хранятся массивы объектов webinars и videos
Используется в событиях: lesson_changed, lesson_start_days, lesson_start_hours.
Объект платежа
-
userId (integer) - ID ученика
-
paymentId (integer) - ID платежа
-
summa (integer) - Сумма платежа
-
userSubscriptionId (integer) - ID абонемента ученика
-
date (string) - Дата оплаты
Используется в событиях: payment_new.
Объект записи на занятие
-
lessonRecordId (integer) - ID записи на занятие
-
free (boolean) - Бесплатная запись
-
test (boolean) - Пробная запись на занятие
-
skip (boolean) - Не учитывать запись в количестве занятых мест
-
visit (boolean) - Статус посещения
-
userId (integer) - ID ученика
-
lessonId (integer) - ID занятия
-
createdAt (string) - Дата создания
-
goodReason (boolean) - Уважительная причина отсутствия
-
joinStats (object) - Статистика записи в группу
Используется в событиях: sub_lesson_in_debt, lesson_record_new, lesson_record_changed.
Объект отмененной записи
-
classId (integer) - ID группы
-
userId (integer) - ID ученика
-
lessonId (integer) - ID занятия
Используется в событиях: lesson_record_deleted.
Объект абонемента пользователя
-
userSubscriptionId (integer) - ID абонемента
-
userId (integer) - ID ученика
-
statusId (integer) - ID статуса абонемента
-
visitedCount (integer) - Количество списанных занятий в абонементе
-
visitCount (integer) - Количество занятий в абонементе
-
remindSumm (integer) - Сумма долга к оплате
-
endDate (string) - Дата окончания действия
-
sellDate (string) - Дата продажи
-
beginDate (string) - Дата начала действия
-
remindDate (string) - Срок оплаты долга
Используется в событиях: sub_days_next_payment, sub_lessons_left, sub_end_days.
Объект двух пропущенных занятий подряд
-
classId (integer) - ID группы
-
userId (integer) - ID ученика
-
lessonIds (array[integer]) - ID последних двух пропущенных занятий
Используется в событиях: user_consecutive_visit_missed_2.
Объект оценки
-
lessonId (integer) - ID занятия
-
userId (integer) - ID ученика
-
type (string) - Тип оценки, home либо lesson
-
value (integer) - Оценка
Используется в событиях: lesson_mark_set, lesson_mark_deleted.
Объект задания
-
lessonId (integer) - ID занятия
-
files (array[integer]) - Список ID прикрепленных файлов
-
type (string) - Тип задания, home либо lesson
-
showToUser (boolean) - Доступно ли задание ученику для просмотра
Используется в событиях: lesson_task_new, lesson_task_changed.
Поле Init
Содержит информацию о том, кто инициировал событие. Формат объекта init:
{ "from": "CRM", // Откуда было вызвано событие "managerId": 65 // ID менеджера }Поле from может принимать значения:
-
CRM - событие вызвано из CRM, в init добавляется managerId - ID менеджера
-
import - событие вызвано из импорта, в init добавляется managerId - ID менеджера
-
LK - событие вызвано из Личного Кабинета ученика, в init добавляется userId - ID ученика
-
widget - событие вызвано из Виджетов, в init добавляется widgetId - ID виджета
-
integration - событие вызвано из Интеграции, в init добавляется integrationId - ID интеграции
-
API - событие вызвано из API
Поле changedFields
Содержит массив измененных полей. Доступно для следующих событий:
-
user_changed - Информация об ученике изменилась
-
user_changed_state - Статус ученика изменился
-
join_changed - Информация о записи в группу изменилась
-
join_changed_state - Статус записи в группу изменился
-
class_changed - Информация о группе изменилась
-
lesson_changed - Информация о занятии изменилась
-
lesson_record_changed - Информация о записи на занятие изменилась
-
lesson_task_changed - Информация о задании изменилась