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

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

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

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

Рассмотрим:

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

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

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

Список веб-хуков

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

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

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

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

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

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

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

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

Адрес запроса

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

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

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

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

Тело POST запроса

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

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

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

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

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

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

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

1. Отправляем веб-хуки до трех раз на одно событие, если endpoint не ответил 200. Клиентский сервис должен ответить за три секунды.

2. В заголовке запроса отправляем заголовок PS-WEBHOOK_EVENT-ID, в котором указываем ID запроса. Этот заголовок можно использовать на клиентской части для идентификации запроса и проверки уникальности.

3. Первая отправка идет через 5 секунд, вторая через 240, третья через 480.

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

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

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

Лог события

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Видео по теме