¶ Создание Webhook
Webhook – это механизм оповещения сторонней системы о событиях, произошедших в Рососмотр. Сторонняя система в данном случае – ваш сервер или настроенный на приём оповещений сервис.
Например: https://webhook.site, https://www.integromat.com
При возникновении одного из событий, отмеченного галочкой, наш сервер отправит запрос по указанному в url адресу. Запрос отправляется методом POST. В header запроса Content-Type: application/json. В теле запроса json с данными. Содержимое зависит от события.
Если в ответ на запрос приходит код 50X или невозможно установить соединение с принимающим сервером из-за сетевой ошибки (тайм-аут соединения, ошибки DNS и прочие), тогда запрос будет отправлен повторно. Повторных попыток – 5 штук с интервалами [2, 10, 60, 300] секунд. В json-пакете в поле attempt будет отмечено, какая попытка по счёту, но только для (attempt >= 2). Механизм автоповторов работает для всех webhook'ов и нужен на случай, если принимающий сервер временно недоступен.
Сохраните webhook, чтобы появилась возможность отправить тестовый запрос на указанный url. Если отмечено несколько событий, тогда тестовый запрос будет содержать данные, подходящие по структуре под одно из выбранных событий. Любые изменения в webhook'е необходимо сохранять перед выполнением тестового запроса.
Внимание! Не ограничивайте на своём сервере приём сообщений по исходящему IP тестовых запросов. Не гарантируется, что все запросы будут приходить с одного и того же IP в дальнейшем. Другими словами, если вы включите наш IP в белый список, то позже можете не получить оповещения, потому что они могут прийти с других IP.
Создание нового WebHook
После нажатия кнопки добавить открывается форма создания Webhook
¶ Описание событий:
¶ Новый осмотр
| Особенности | При создании осмотра (когда осмотр впервые записывается в БД сервера) |
| Охват | Учитывается роль владельца webhook'а (кто создал, тот и владелец). Администраторам отправляются сообщения обо всех новых осмотрах компании. Администраторам групп – осмотры тех групп доступа, к которым относится сам администратор групп. |
| Особенности | В момент создания осмотра в БД, к нему не привязаны никакие данные, кроме ключевых определяющих, таких как: кто создал, по какой схеме, для какой компании. Для постобработки через api интеграции удобнее использовать событие "Осмотр изменил статус". |
Пример содержимого запроса:
{ "event": "inspection_created", "occurred_at": "2023-01-17 13:32:53", "model": "Inspection", "id": 2442, "data": { "created_by": { "id": 742, "email": "operator@the.best", "phone": "+74440001122", "role": "callcenter" }, "status": "draft", "object_name": "Авто для осмотра", "service_name": "500 AUTO", "service_uuid": "6c8e1120-b955-11e9-8e50-279abb86ccf7", "is_web_created": true, "created_via": { "interface": "integrapi", "channel": "clone" } }}
¶ Поделились осмотром с кем-либо
| Срабатывает | Когда осмотром поделились с ещё одним пользователем через мобильное приложение, административный интерфейс или через api интеграции. |
| Охват | Учитывается роль владельца webhook'а (кто создал, тот и владелец). Администраторам отправляются сообщения обо всех осмотрах компании. Администраторам групп – информация об осмотрах тех групп доступа, к которым относится сам администратор групп. |
| Особенности | Тот, кто делится осмотром, указывает о получателе ФИО и номер телефона. Система находит получателя в БД, либо создаёт нового пользователя с ролью "клиент". В данных оповещения присылаем сведения как о получателе, так и о том, кто поделился осмотром. |
Пример содержимого запроса:
{ "event": "inspection_shared", "occurred_at": "2023-01-17 13:32:53", "model": "Inspection", "id": 2442, "data": { "created_by": { "id": 742, "email": "operator@the.best", "phone": "+74440001122", "role": "callcenter" }, "status": "repeat", "object_name": "Авто для осмотра", "service_name": "500 AUTO", "service_uuid": "6c8e1120-b955-11e9-8e50-279abb86ccf7", "is_web_created": true, "created_via": { "interface": "integrapi", "channel": "clone" }, "shared_by": { "id": 1042, "email": "old@client.xx", "phone": "+79990008855", "role": "client" }, "shared_for": { "id": 12042, "email": "new@client.xx", "phone": "+70001112233", "role": "client" } }}
¶ В осмотре впервые начат процесс съёмки
| Срабатывает | Когда на сервер приходит первый запрос об инициализации новой съёмки для осмотра |
| Охват | Учитывается роль владельца webhook'а (кто создал, тот и владелец). Администраторам отправляются сообщения обо всех осмотрах компании. Администраторам групп – оповещение об осмотрах из тех групп доступа, к которым относится сам администратор групп. |
| Особенности | Фиксируем момент, когда пользователь впервые дошёл до фотографирования. Можно считать данное событие фактическим началом выполнения осмотра, так как заполнение формы к осмотру достаточно часто не означает, что пользователь собирается фотографировать что-либо. Учитывайте, что оповещение приходит в момент, когда сервер получает данные о начале съёмки, а не в момент как такового начала съёмки. Пользователь может находиться в это время в оффлайне. |
Пример содержимого запроса:
{ "event": "inspection_first_process", "occurred_at": "2023-01-17 13:32:53", "model": "Inspection", "id": 5642, "data": { "created_by": { "id": 4242, "email": "foo@email.xx", "phone": "+70010023456", "role": "client" }, "status": "draft", "object_name": "Авто для осмотра", "service_name": "500 AUTO", "service_uuid": "6c8e1120-b955-11e9-8e50-279abb86ccf7", "is_web_created": false, "created_via": { "interface": "mobapp", "channel": "common" } }}
¶ Осмотр изменил статус
| Срабатывает | После установки осмотру нового статуса (при изменении статуса в БД сервера) |
| Охват | Учитывается роль владельца webhook'а (кто создал, тот и владелец). Администраторам отправляются сообщения обо всех осмотрах компании. Администраторам групп – изменения статусов осмотров тех групп доступа, к которым относится сам администратор групп. |
| Особенности |
При оповещении используются алиасы статусов, а не их текстовое представление для пользователей. Ниже перечислены статусы с их базовыми текстовками (для сборок могут быть заданы персональные текстовки – здесь они не учтены). Перечень может быть расширен позже, не ограничивайте вариантивность на приёмной стороне тем, что здесь перечислено.
|
Пример содержимого запроса:
{ "event": "inspection_status_changed", "occurred_at": "2023-01-17 13:32:53", "model": "Inspection", "id": 2442, "data": { "created_by": { "id": 742, "email": "operator@the.best", "phone": "+74440001122", "role": "callcenter" }, "status": "expertise", "object_name": "Авто для осмотра", "service_name": "500 AUTO", "service_uuid": "6c8e1120-b955-11e9-8e50-279abb86ccf7", "is_web_created": true, "created_via": { "interface": "integrapi", "channel": "clone" } }}
¶ Осмотр отправлен на проверку
| Срабатывает | Когда на сервер приходит запрос, сформированный при нажатии на кнопку "Отправить на проверку" |
| Охват | Учитывается роль владельца webhook'а (кто создал, тот и владелец). Администраторам отправляются сообщения обо всех осмотрах компании. Администраторам групп – оповещение об осмотрах из тех групп доступа, к которым относится сам администратор групп. |
| Особенности | Система отдельно фиксирует факт нажатия на кнопку "Отправить на проверку". Чтобы действие выполнилось, необходимо соблюдение нескольких критериев, в числе которых полнота выполнения схемы осмотра. Запрос "отправить на проверку" приходит на сервер, как правило, до прихода файлов. Тем не менее, не гарантируется, что по webhook'ам сначала придёт оповещение "осмотр отправлен на проверку", и только после этого оповещение о смене статуса на экспертизу. Не выстраивайте на своей стороне логику работы, предполагая строгую последовательность оповещений. Она не строгая! |
Пример содержимого запроса:
{ "event": "inspection_ended_by_user", "occurred_at": "2023-01-17 13:32:53", "model": "Inspection", "id": 2442, "data": { "created_by": { "id": 742, "email": "operator@the.best", "phone": "+74440001122", "role": "callcenter" }, "ended_by": { "id": 4242, "email": "foo@email.xx", "phone": "+70010023456", "role": "client" }, "status": "draft", "object_name": "Авто для осмотра", "service_name": "500 AUTO", "service_uuid": "6c8e1120-b955-11e9-8e50-279abb86ccf7", "is_web_created": true, "created_via": { "interface": "integrapi", "channel": "clone" } }}
¶ Осмотр отправлен на согласование
| Срабатывает | Когда осмотр передаётся на согласование (обычно, во время проверки при внесении изменений экспертом) |
| Охват | Учитывается роль владельца webhook'а (кто создал, тот и владелец). Администраторам отправляются сообщения обо всех осмотрах компании. Администраторам групп – оповещение об осмотрах из тех групп доступа, к которым относится сам администратор групп. |
Пример содержимого запроса:
{ "event": "inspection_approval", "occurred_at": "2023-01-17 13:32:53", "model": "Inspection", "id": 2442, "data": { "created_by": { "id": 742, "email": "operator@the.best", "phone": "+74440001122", "role": "callcenter" }, "status": "approval", "object_name": "Авто для осмотра", "service_name": "500 AUTO", "service_uuid": "6c8e1120-b955-11e9-8e50-279abb86ccf7", "is_web_created": true, "created_via": { "interface": "integrapi", "channel": "clone" } }}
¶ Осмотр загружен на сервер и готов к проверке (экспертиза)
| Срабатывает | В момент, когда осмотр переводится на стороне сервера в статус Экспертиза |
| Охват | Учитывается роль владельца webhook'а (кто создал, тот и владелец). Администраторам отправляются сообщения обо всех осмотрах компании. Администраторам групп – оповещение об осмотрах из тех групп доступа, к которым относится сам администратор групп. |
| Особенности |
Статус экспертиза устанавливается осмотру сервером при одновременном выполнении следующих критериев:
Внимание! Осмотр может быть переведён на проверку принудительно через административный интерфейс или api интеграции даже при невыполнении указанных выше критериев. |
Пример содержимого запроса:
{ "event": "inspection_status_changed_to_expertise", "occurred_at": "2023-01-17 13:32:53", "model": "Inspection", "id": 5642, "data": { "created_by": { "id": 4242, "email": "foo@email.xx", "phone": "+70010023456", "role": "client" }, "status": "expertise", "object_name": "Авто для осмотра", "service_name": "500 AUTO", "service_uuid": "6c8e1120-b955-11e9-8e50-279abb86ccf7", "is_web_created": false, "created_via": { "interface": "mobapp", "channel": "common" } }}
¶ Завершена обработка фотографий сервисом распознавания Dbrain или сработал timeout
| Срабатывает | В момент, когда все подходящие фотографии осмотра обработаны сервисом распознавания Dbrain либо время ожидания обработки истекло |
| Охват | Учитывается роль владельца webhook'а (кто создал, тот и владелец). Администраторам отправляются сообщения обо всех осмотрах компании. Администраторам групп – оповещение об осмотрах из тех групп доступа, к которым относится сам администратор групп. |
| Особенности |
В ответ будет добавлен раздел
|
Пример содержимого запроса:
{ "event": "inspection_dbrain_processed", "occurred_at": "2023-01-17 13:32:53", "model": "Inspection", "id": 5642, "data": { "created_by": { "id": 4242, "email": "foo@email.xx", "phone": "+70010023456", "role": "client" }, "status": "expertise", "object_name": "Авто для осмотра", "service_name": "500 AUTO", "service_uuid": "6c8e1120-b955-11e9-8e50-279abb86ccf7", "is_web_created": false, "created_via": { "interface": "mobapp", "channel": "common" }, "dbrain_result": { "status": "partially_complete", "sent": 6, "received": 3 } }}
¶ Зарегистрировался новый пользователь (самостоятельно через приложение)
| Срабатывает | Когда новый пользователь проходит регистрацию самостоятельно в мобильном приложении. Оповещение отправляется после подтверждения пользователем своего номера телефона либо после активации пользователя, если регистрация проводится без подтверждения телефонного номера. |
| Охват | Учитывается роль владельца webhook'а (кто создал, тот и владелец). Администраторам отправляются сообщения обо всех новых пользователях, привязываемых к компании администратора. Администраторам групп – информация о новых пользователях, которые при регистрации автоматически связываются с группами доступа, к которым относится сам администратор групп. |
Пример содержимого запроса:
{ "event": "user_self_registered", "occurred_at": "2023-01-17 13:32:53", "model": "User", "id": 4242, "data": { "email": "foo@email.xx", "phone": "+70010023456", "role": "client" }}
¶ Добавлен новый пользователь (администратором, через api, и т.п.)
| Срабатывает |
Когда новый пользователь добавляется в систему, но не в следствие саморегистрации через приложение (для этого есть отдельное событие), а когда пользователя добавили через один из вспомогательных интерфейсов:
|
| Охват | Учитывается роль владельца webhook'а (кто создал, тот и владелец). Администраторам отправляются сообщения обо всех новых пользователях, привязываемых к компании администратора. Администраторам групп – информация о новых пользователях, которые при создании были привязаны к группам доступа, к которым относится сам администратор групп. |
| Особенности | Пользователь мог быть добавлен программно (через integrapi) без привязки к группам доступа, затем отдельным запросом эта привязка может быть выставлена. В таком случае, администратор групп не получит оповещение, но администратор получит. |
Пример содержимого запроса:
{ "event": "user_added", "occurred_at": "2023-01-17 13:32:53", "model": "User", "id": 4242, "data": { "email": "foo@email.xx", "phone": "+70010023456", "role": "client", "created_by": { "id": 742, "email": "boo@email.xx", "phone": "+70010023789", "role": "admin" }, "interface": "web" }}
¶ Новое сообщение из мобильного приложения в техподдержку
| Срабатывает | После отправки пользователем из мобильного приложения обращения в техническую поддержку. |
| Охват | Учитывается роль владельца webhook'а (кто создал, тот и владелец). Администраторам отправляются сообщения от пользователей, привязанных к компании администратора. Администраторам групп – сообщения от пользователей, которые привязаны к тем же группам доступа, что и сам администратор групп (хотя бы к одной из групп). |
| Особенности | При обращении в поддержку пока что известно крайне мало информации. Фактически, опираться при обработке таких обращений следует на текст сообщения и то, кто его отправил. |
Пример содержимого запроса:
{ "event": "support_mob_issue_created", "occurred_at": "2023-01-17 13:32:53", "model": "FeedbackLog", "id": 7, "data": { "text": "Я что-то нажала, и у меня всё сломалось!", "created_by": { "id": 742, "email": "dumby@email.xx", "phone": "+70010023700", "role": "client" } }}
¶ На сервер пришла ещё одна точка GPS-координат к осмотру
| Срабатывает | Когда на сервер приходит очередная GPS-точка из мобильного приложения И осмотр уже передан в экспертизу или переведён в один из завершающих статусов |
| Охват | Учитывается роль владельца webhook'а (кто создал, тот и владелец). Администраторам отправляются сообщения обо всех осмотрах компании. Администраторам групп – оповещение об осмотрах из тех групп доступа, к которым относится сам администратор групп. |
| Особенности | Данные об осмотрах приходят на сервер по порядку: сначала общие метаданные, затем файлы, в последнюю очередь информация с датчиков и GPS-координаты. Допускается, что на момент перехода осмотра в статус экспертиза GPS-координаты из приложения ещё не пришли на сервер. Можно подписаться на событие, чтобы получать все пришедшие GPS-координаты после перехода осмотра в экспертизу. На каждую пришедшую точку будет вызван webhook. В том числе, на повторяющиеся координаты. Если осмотр перевести на повтор, webhook не будет вызываться. Флаг gps_source определяет источник координат: gps_source: mob – мобильное приложение; gps_source: admin – администратор задал уточнённые координаты вручную через web-интерфейс. |
Пример содержимого запроса:
{ "event": "inspection_gps_received", "occurred_at": "2023-01-17 13:32:53", "model": "Inspection", "id": 2442, "data": { "created_by": { "id": 742, "email": "operator@the.best", "phone": "+74440001122", "role": "callcenter" }, "status": "expertise", "object_name": "Авто для осмотра", "service_name": "500 AUTO", "service_uuid": "6c8e1120-b955-11e9-8e50-279abb86ccf7", "is_web_created": true, "created_via": { "interface": "integrapi", "channel": "clone" }, "lat": 48.208477999999999, "lon": 16.373197999999999, "gps_source": "admin" }}
¶ Изменение или добавление схемы осмотра
| Срабатывает | При изменении схемы осмотра или при создании новой схемы |
| Охват | Учитывается текущий доступ пользователя, от имени которого webhook добавлен в систему. Данные отправляются при условии, что пользователь имеет доступ к схеме. |
| Особенности | Событие срабатывает как при внесении изменений, так и при создании новой схемы, если сразу известно, что у пользователя, создавшего webhook, есть права доступа на схему. Гарантировано регистрируются изменения, приводящие к увеличению версии схемы. Например, редактирование шагов или удаление этапов. Не гарантируется, но webhook может быть отправлен, также, по другим событиям внесения правок в схему. Негарантированные изменения считаются некритичными для процесса осмотра. Для существенных изменений всегда повышается версия схемы. |
Пример содержимого запроса:
{ "event": "insure_service_changed", "occurred_at": "2023-01-17 13:32:53", "model": "InsureService", "uuid": "acecbb50-b948-11e9-9aee-41e83687f92c", "data": { "name": "Общий осмотр объекта силами клиента" }}