WebHook - интеграция с внешними системами

В системе Parts-Soft появился функционал WebHook, который будет полезен при интеграции нашей системы с Вашими бизнес-процессами.
Этот механизм позволяет отправлять уведомления во внешние системы при создании, изменении, удалении объектов в нашей системе.

По данному разделу доступна подробная ВИДЕО инструкция.

ОБРАТИТЕ ВНИМАНИЕ! Для использования функционала WebHook требуется программист.
Сотрудники техподдержки не занимаются настройкой веб-хуков для интеграции с внешними системами.

Рассмотрим:

• создание веб-хука на примере передачи информации о том, что пришел заказ на обратный звонок;
• тестирование веб-хука;
• настройка веб-хука с отправкой информации в формате JSON.

Создание веб-хука

ШАГ 1.   В панели администратора системы Parts-Soft перейдем в меню Служебные → Справочники → Интеграции → Веб-хуки и нажмем на кнопку «Создать».

Фото 1. Список веб-хуков

ШАГ 2.  В карточке WebHook выберем модель (1) (для нашего примера "Лид заказ обратного звонка") и метод запроса (2) ("POST").

Отметим галочкой опцию Активен (3) для отработки запроса.
Выберем действия (4), на которые он будет отрабатывать:

• На создание;
• На обновление;
• На удаление.

Фото 2. Создание веб-хука

ШАГ 3.    Укажем адрес запроса.

Для получения тестового адреса обратимся к сервису Webhook.site. 
Создадим новый адрес и скопируем его.

Фото 3. Получение тестового адреса

Вернемся к карточке веб-хука в панели администратора Parts-Soft. Вставим скопированный URL в поле Адрес запроса.

Фото 4. Адрес запроса

ШАГ 4.   В Теле POST запроса будем отправлять во внешнюю систему информацию о том, что пришел заказ на обратный звонок.

Здесь можно использовать liquid. Корневой объект - это item.
Объект, который выбран в качестве модели (в нашем случае "Лид заказ обратного звонка"), будет инициализирован под именем item.
Доступные поля описаны в справочном разделе Шаблоны писем → глава Переменные шаблона.

Создадим отправку телефона и имени.
ДЛЯ СПРАВКИ: Если запрос содержит спец символы, его необходимо кодировать. Для этого используем функцию url_encode//

Сохраним созданный запрос.

Фото 5. Тело POST запроса

ШАГ 6.   Для того чтобы создавался лид при заказе обратного звонка необходимо в меню Сайт → Общие настройки найти опцию Учитывать лиды и отметить ее галочкой.
Не забываем сохранить настройки.

Фото 6. Общие настройки сайта

Тестирование веб-хука

На сайте откроем форму обратного звонка. Укажем имя и телефон и отправим заказ на обратный звонок.

Фото 7. Форма обратного звонка

Перейдем в панель администратора к списку веб-хуков (см. фото 1). Откроем лог срабатываний созданного веб-хука.
Проверяем, что в таблице появилось событие. Для него отображается время и количество попыток отправки веб-хука.

ВАЖНЫЕ МОМЕНТЫ:

1. Отправляем веб-хуки до трех раз на одно событие, если endpoint не ответил 200.
    Клиентский сервис должен ответить за три секунды.
2. В заголовке запроса отправляем заголовок PS-WEBHOOK_EVENT-ID, в котором указываем ID запроса.
    Этот заголовок можно использовать на клиентской части для идентификации запроса и проверки уникальности.
3. Первая отправка идет через 5 секунд, вторая через 240, третья через 480.

Фото 8. События веб-хука

Нажав на иконку лупы, просмотрим историю попыток (лог события).

В нашем случае при 1-й попытке получен ответ, указанный нами на сайте для тестирования при получении адреса (см. фото 3), с кодом ответа 200.

Фото 9. Лог события

Вернемся к сервису для тестирования Webhook.site. Видим, что запрос действительно пришел.

Фото 10. Проверка в сервисе для тестирования

Настройка веб-хука с отправкой информации в JSON

Рассмотрим пример отправки информации о создании нового заказа в формате JSON.

ШАГ 1.   Создадим новый веб-хук (см. фото 1). 

Заполним карточку:

• Модель (1) – Заказ клиента;
• Метод запроса (2) – POST;
• Адрес запроса (3) – для теста вновь воспользуемся сервисом Webhook.site (см. фото 3);
• отметим галочкой опцию Активен (4);
• отметим галочкой опцию На обновление (5);
• отметим галочкой опцию Отправлять JSON в POST (6) – при активной опции поле Тело POST запроса использоваться не будет.

Сохраним настройки.

Фото 11. Создание веб-хука с использованием JSON

ШАГ 2.   Внесем изменения в заказ клиента (обновим его).

В меню Заказы → По группам отредактируем один из клиентских заказов. К примеру, укажем комментарий.

Фото 12. Обновление клиентского заказа

ШАГ 3.   Просмотрим лог срабатываний веб-хука. 

В списке веб-хуков найдем модель "Заказ клиента" и перейдем к списку событий. Видим, что есть попытка срабатывания со статусом 200.
Можно просмотреть историю попыток.

Фото 13. События веб-хука

ШАГ 4.   Проверим результат в сервисе для тестирования. Видим, что пришел POST запрос со всей информацией по заказу.

Фото 14. Проверка в сервисе для тестирования

---