Универсальный вебхук¶

Универсальный вебхук - это инструмент для настройки входящей webhook-интеграции. С его помощью можно принимать данные из внешних сервисов, создавать заявки в Roistat и передавать их в подключенную CRM.

Инструмент подходит, если вы используете сервис, которого нет в каталоге готовых интеграций Roistat, но этот сервис умеет отправлять данные через webhook. Например, так можно подключить форму, квиз, виджет, конструктор заявок или другой внешний сервис.

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

Если вам нужно передавать заявки в Roistat в фиксированном формате, используйте стандартную интеграцию через Webhook.

Как работает Универсальный вебхук¶

1. Вы создаете webhook-интеграцию в Roistat.
2. Roistat генерирует уникальный URL вебхука.
3. Вы копируете URL и указываете его во внешнем сервисе.
4. Вы получаете или загружаете пример входящих данных.
5. Roistat показывает структуру полученных данных.
6. Вы сопоставляете поля из вебхука с полями заявки и CRM.
7. Вы настраиваете поведение интеграции: создание заявки, отправку заявки в CRM, обратный звонок и сценарии отправки заявок.
8. После активации вебхука новые входящие запросы создают заявки в Roistat.

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

Создание Универсального вебхука¶

• В проекте Roistat откройте раздел Интеграции.
• Перейдите в раздел Универсальные вебхуки.

• Нажмите кнопку Добавить универсальный вебхук
• Укажите название вебхука. Используйте понятное название, чтобы позже быстро найти нужную интеграцию в списке.
• Нажмите Сгенерировать URL. Скопируйте полученный URL и укажите его во внешнем сервисе, из которого хотите передавать заявки.

• Сохраните настройку.

Получение образца данных¶

Чтобы настроить сопоставление полей, Roistat должен получить пример данных от внешнего сервиса.

Есть несколько способов передать пример:

• получить входящий запрос от внешнего сервиса на URL, который сгенерировал Roistat;
• вставить пример данных вручную;
• загрузить файл с примером данных.

После получения образца Roistat покажет структуру данных: список полей, вложенные поля и примеры значений. Эти данные используются для настройки сопоставления.

Сопоставление полей¶

На шаге сопоставления укажите, какие значения из входящего вебхука нужно передавать в поля заявки и CRM.

Вы можете сопоставить данные вебхука со следующими полями:

• имя клиента;
• телефон;
• электронная почта;
• название заявки;
• комментарий заявки;
• пользовательские поля CRM, если они доступны в подключенной CRM-интеграции.

Для каждого поля можно выбрать один из вариантов значения:

• поле из входящего вебхука;
• статическое значение, например текст или число;
• переменную Roistat.

Например, если внешний сервис передает номер телефона в поле client.phone, выберите это поле в настройке сопоставления для поля Телефон. Если нужно передавать одинаковый комментарий для всех заявок из этой интеграции, укажите статическое значение в поле Комментарий заявки.

Настройка поведения интеграции¶

После сопоставления полей настройте, что Roistat должен делать с заявками, полученными через Универсальный вебхук.

Доступные настройки:

• Отправлять заявки в CRM - если опция включена и в проекте настроена CRM-интеграция, заявки будут отправляться в CRM. Если отключить опцию, заявки будут создаваться в Roistat, но не будут отправляться в CRM.
• Инициировать обратный звонок по номеру клиента - если опция включена, Roistat сможет инициировать обратный звонок по номеру клиента из заявки.
• Создавать заявки без контактных данных - используйте эту настройку, если внешний сервис может передавать заявки без телефона или email.
• Сценарии отправки заявок - позволяют настраивать правила отправки заявок в CRM в зависимости от параметров заявки.

Сценарии отправки заявок работают по тому же принципу, что и в других интеграциях Roistat: с их помощью можно настроить условия, по которым заявки будут отправляться в CRM. В условиях сценариев можно использовать поля, полученные из вебхука.

Активация вебхука¶

После настройки сопоставления полей и поведения интеграции активируйте вебхук.

Для активации нужно:

• указать название вебхука;
• настроить сопоставление хотя бы одного поля заявки;
• проверить настройки поведения интеграции;
• перевести вебхук в активный статус.

После активации новые входящие запросы на URL вебхука будут обрабатываться Roistat. Если данные корректны, в Roistat будет создана заявка. Если в проекте подключена CRM и включена отправка заявок, заявка будет отправлена в CRM.

Управление вебхуками¶

В разделе Универсальные вебхуки отображается список созданных webhook-интеграций.

В списке можно посмотреть:

• статус вебхука;
• название;
• дату создания;
• дату обновления;
• доступные действия.

С вебхуком можно выполнить следующие действия:

• включить или выключить;
• открыть и изменить настройки;
• клонировать;
• удалить.

При клонировании создается новая webhook-интеграция с отдельным URL. Настройки и сопоставление полей клонируются из исходного вебхука, но новый URL нужно отдельно указать во внешнем сервисе.

Проверка работы вебхука¶

Чтобы проверить, что интеграция работает корректно:

1. Убедитесь, что вебхук активирован.
2. Отправьте входящий запрос из внешнего сервиса на URL вебхука.

3. В Roistat откройте список созданных заявок.

   

4. Найдите заявку, созданную через Универсальный вебхук.

5. Проверьте, что поля заявки заполнены корректно.
6. Если включена отправка в CRM, проверьте, что заявка появилась в CRM.

Если заявка не появилась в Roistat или CRM, проверьте настройки сопоставления полей и историю вебхуков.

История вебхуков¶

История вебхуков помогает проверить, какие запросы получил Roistat и как они были обработаны.

В истории можно посмотреть:

• дату запроса;
• тип;
• метод;
• URL;
• код ответа;
• тело запроса;
• тело ответа;
• действия.

Для Универсального вебхука можно открыть историю по конкретной webhook-интеграции. Это удобно, если в проекте настроено несколько вебхуков и нужно проверить запросы только по одному из них.

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

Частые проблемы¶

Особенности текущей версии¶

• Универсальный вебхук поддерживает данные в форматах application/json и application/x-www-form-urlencoded. XML не поддерживается;
• вебхук создает новые заявки, но не обновляет существующие сущности;
• одна webhook-интеграция использует один фиксированный маппинг полей;
• преобразования значений не поддерживаются: нельзя настраивать формулы, склейку значений или изменение формата данных;
• массивы можно сопоставить только целиком как одно текстовое значение;
• образец данных не сохраняется между сессиями редактирования. Если вы позже снова откроете настройку вебхука, для редактирования сопоставления нужно будет заново получить или загрузить пример данных.