Триггерный webhook

Webhook — это техническое сообщение, которое посылает наша система другой системе. 

Некоторые примеры сценариев, для которых пригодятся вебхуки:

• прогрев клиента через отправку сообщения из стороннего сервиса (например, если клиент не читает ваши сообщения в Телеграм, вы можете отправить вебхук в сервис для отправки СМС либо сообщений в Whatsapp, и отправить ему сообщение прямо на номер телефона);
• запрос и получение данных из стороннего сервиса (например, вы запрашиваете данные о балансе клиента и выводите эти данные в сценарии чат-бота, который проходит клиент);
• отправка данных пользователя в сторонние системы (например, вы можете отправить webhook с данными пользователя в Битрикс24, когда он кликнет на кнопку “Купить”. Битрикс поймёт эту команду и запишет себе нового пользователя или обновит имеющегося.).

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

Давайте посмотрим, как настроить триггерную отправку вебхука.

Зайдите в раздел Триггерные сообщения и создайте новое сообщение. На шаге Содержание выберите тип - Webhook:

Откроется интерфейс для настройки вебхука:

На этом шаге нужно выбрать метод запроса, указать URL-адрес для отправки запроса, указать тело запроса. Можно также указать Query-параметры и добавить заголовки запроса. 

Метод запроса 

• POST: позволяет отправлять данные о лиде из Carrot quest в другие системы. Подробнее о том, какие данные отправит такой вебхук - в документации.
  
  
• GET: позволяет запросить данные в стороннем сервисе и записать их в карточку лида Carrot quest. Ответ от стороннего сервиса принимается и записывается в событие и его атрибуты.

  У GET-запроса нет тела, все данные указываются в URL.
  
  

• PATCH: получает данные в стороннем сервисе и заменяет данные лида на стороне Carrot quest.
  
  

• PUT: получает данные в стороннем сервисе и дополняет информацию о лиде в Carrot quest полученными данными.
  
  

• DELETE: удаляет указанные данные на стороне Carrot quest. Обычно не имеет тела, но бывают исключения.
  
  

Тело запроса

Тело запроса содержит данные, которые будут отправлены на сервер. Оно представлено в формате JSON. Вы можете использовать язык шаблонов Jinja для динамического заполнения тела запроса переменными, например, записанными свойствами или событиями из карточки пользователя. Если сервис, в который вы отправляете запрос, принимает Python, можно использовать его.

В теле нужно указать параметры и переменные. Можно добавить свойство пользователя в Jinja - подробнее об этом читайте тут. 

Пример 1: в теле запроса передаём свойства пользователя с помощью Jinja: 

{
 "name": "{{ user['$name'] }}",
 "email": "{{ user['$email'] }}",
 "phone": "{{ user['$phone'] }}",
 "order_id": "{{ user['order_id'] }}"

Пример 2: в теле запроса передаём персонализированный текст СМС-сообщения и номер телефона с помощью Jinja

{
 "route": "sms",
 "from": "<SENDER_NAME>",
 "to": "{{ user['$phone'] }}",
 "text": "Ваш заказ №{{ event['номер заказа'] }} приянт и будет доствален по адресу {{ event['адрес доставки'] }} в {{ event['время доставки'] }}."

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

URL-адрес и Query-параметры

URL-адрес — это адрес сервера, на который будет отправляться запрос. Этот адрес должен быть предоставлен сервисом, с которым вы хотите интегрироваться.

Query-параметры — это дополнительные параметры, которые добавляются к URL-адресу запроса. Они используются для передачи данных в URL-строке и также могут быть заполнены с использованием Jinja.  

Пример URL с Query-параметрами, где используется Jinja: 

https://your-bitrix24-instance.com/webhook-endpoint?user_id={{ user['$user_id'] }}&order_id={{ user['order_id'] }}

Заголовки запроса

Заголовки запроса передают метаинформацию о запросе. Некоторые заголовки автоматически добавляются системой:

• Host: Адрес сервера.
• Content-Length: Длина тела запроса
• Content-Type: Тип содержимого (application/json).

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

• Authorization: Используется для передачи токенов доступа.
• Accept: Указывает, какие форматы данных сервер может отправить в ответ.
• User-Agent: Информация о клиенте, отправляющем запрос.

Обратите внимание: не рекомендуется хранить и передавать конфиденциальные данные в заголовках запроса.

Условия отправки

После настройки тела вебхука можно перейти на шаг Когда отправлять. Укажите событие, при срабатывании которого будет отправляться webhook.

❗ Важно: Если добавить несколько событий в качестве триггеров, то webhook будет отправляться при срабатывании ЛЮБОГО из триггеров.

Выберите, через какое время после срабатывания триггера будет отправляться webhook (сразу после срабатывания или через промежуток времени), а так же в какое время будет отправляться webhook: в любое или только в определенное время суток.

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

Можно отправить вебхук всем пользователям, либо тем, кто соответствует хотя бы одному условию:

“Всем” эквивалентно логическому “И”, т.е. все условия должны быть выполнены. = “Любому” эквивалентно логическому “Или”, т.е. если выполнен хотя бы один фильтр (или даже все), то пользователь проходит.

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

События пользователя
Указываются события, которые выполнял пользователь к моменту срабатывания триггера.

❗ Важно: Если у триггерного сообщения стоит задержка показа (см. предыдущий шаг “Выбор триггера”), то свойства и события проверяются через это время: сработал триггер — прошло N времени — фильтры проверили пользователя.

❗ Важно: Не обязательно каждый раз выбирать события и свойства пользователя, можно выбрать сохранённый сегмент.

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

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

Если всё настроено верно, то нажмите “Сохранить и запустить”, если необходимо, чтобы сообщение сразу начало свою работу, или на “Сохранить и запустить позже”.

Подробнее о webhook читайте в документации.