Webhook

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

Уведомлять внешние системы, когда клиент совершает действие в Journey
Отправлять данные о клиентах в инструменты аналитики
Запускать отправку email, SMS или WhatsApp от сторонних сервисов при определенных событиях в Journey

Как настроить элемент Webhook

Добавьте элемент Webhook

Перетащите элемент Webhook на холст. Разместите Webhook в любом месте, учитывая, какую информацию из Journey вы собираетесь отправлять в сторонний сервис.

Элемент Webhook на холсте с настройками имени и запроса

Назовите шаг Webhook и укажите URL и тип запроса

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

Далее, в поле URL укажите URL-адрес запроса, на который должны быть отправлены данные. Рядом с полем URL выберите тип запроса из выпадающего списка REQUEST TYPE: GET или POST.

Интерфейс настройки Webhook, показывающий поле URL и выпадающий список REQUEST TYPE для выбора метода GET или POST

Настройте заголовки

В разделе HEADERS установите тип контента.

По умолчанию тип контента — application/json. Если сервис, в который вы отправляете вебхук, требует другой тип контента, введите соответствующее значение в поле заголовка Content-Type.

Примеры типов контента:

x-www-form-urlencoded
text/plain
text/xml

При необходимости добавьте дополнительные заголовки, нажав + ADD HEADER. Вы можете удалить любой заголовок, нажав на значок ‘x’ рядом с ним.

Добавьте любой заголовок аутентификации, который требует ваша конечная точка, например:

Authorization: Bearer <token>
X-Api-Key: <key>
Authorization: Basic <base64(user:pass)>

Поддерживается только статический секрет в заголовке. Процессы обмена токенами OAuth2, mTLS и подписание запросов на стороне Pushwoosh не поддерживаются. Вы также можете ограничить доступ к конечной точке по IP-адресам Pushwoosh вместо или в дополнение к секрету в заголовке. См. IP-адреса Pushwoosh.

Для HTTP Basic аутентификации, в частности, выполните следующие действия:

Откройте простой текстовый редактор и введите ваше имя пользователя и пароль без пробелов, разделенные двоеточием. Например: myuser:mypass
Закодируйте эту строку в Base64.
Скопируйте полученную строку Base64 (например, bXl1c2VyOm15cGFzcw==).
В настройках вебхука добавьте заголовок Authorization со значением: Basic <ВАША СТРОКА BASE64>. Убедитесь, что после слова “Basic” стоит пробел.

Пример заголовка Authorization для Basic аутентификации в настройках вебхука, показывающий заголовки Content-Type и Authorization

Добавьте тело JSON-запроса

В разделе DATA введите тело вашего JSON-запроса. Убедитесь, что тело запроса имеет правильный формат JSON.

Пример:

{
  "hwid": "{{device:hwid}}"
}

Используйте динамические данные и макросы

Панель DATA BUILDER позволяет вставлять динамическую информацию (например, данные о пользователе, устройстве, тегах или событиях) непосредственно в тело вашего JSON-запроса. С помощью динамических данных вы можете включать значения, специфичные для конкретного пользователя, проходящего через Journey.

Для этого:

Выберите категорию. Вы можете извлекать данные из трех категорий:

Device: Используйте данные об устройстве, когда вам нужна техническая информация, привязанная к устройству пользователя.
Tag: Используйте данные тегов, когда вы хотите отправить информацию, хранящуюся в профиле пользователя.
Event: Используйте данные о событии, когда вебхук должен отправлять значения из события, запустившего Journey.

Значения из инициирующего события остаются привязанными к “путешественнику” на протяжении всего Journey, в том числе и после элемента Time Delay. Они теряются только в том случае, если “путешественник” покидает Journey, например, при отменяющем событии, выходе или по завершении Journey. Если “путешественник” проходит через один и тот же шаг Webhook более одного раза, новый ответ перезаписывает значение, которое было сопоставлено в прошлый раз.

Выберите параметр (например, HWID, любимая категория и т.д.).
Pushwoosh генерирует макрос, который выглядит следующим образом:

{{tag:Language}}

Скопируйте макрос и вставьте его в тело JSON в разделе DATA.

Когда вебхук запускается в активном Journey, Pushwoosh автоматически заменяет макрос фактическим значением для этого пользователя.

Вставка плейсхолдеров динамических данных в тело запроса вебхука

Сопоставьте данные ответа вебхука с переменными

Помимо отправки данных, элемент Webhook может также захватывать данные из полученного ответа и превращать их в переменные. Эти переменные затем можно использовать далее в Journey. Например, установить тег с помощью Update user profile или запланировать Time Delay на основе значения, возвращенного внешним сервисом. Полный пример Journey см. в разделе Использование данных ответа вебхука в вашем Journey.

В разделе RESPONSE MAPPING нажмите + ADD MAPPING и заполните два поля для каждого значения, которое вы хотите захватить:

Path: местоположение значения в теле JSON-ответа
Attribute: имя, которое вы будете использовать для ссылки на это значение далее в Journey

Раздел сопоставления ответа с полями Path и Attribute и кнопкой Add mapping в настройках вебхука

Например, если ваша CRM отвечает:

{
  "data": {
    "user": {
      "id": "789xyz"
    }
  }
}

Установите Path в data.user.id и Attribute в crm_user_id, чтобы захватить этот ID.

Несколько моментов, которые нужно знать о сопоставлении:

Path — это простой путь, разделенный точками (ключи объектов и, для массивов, числовые индексы, например results.0.code). Он не поддерживает подстановочные знаки или фильтры, поэтому может указывать только на одно конкретное значение за раз.
Значения сохраняются в точности так, как они приходят из JSON-ответа (текст, число или true/false). Преобразование типов не производится: 100 сопоставляется как число, а "100" — как текст, и не будет работать в числовом сравнении. Если вы планируете использовать значение в качестве даты в элементе Time Delay, убедитесь, что ваш сервис возвращает его в одном из форматов даты, поддерживаемых Time Delay. Десятичное число (например, 19.99) можно сохранить в тег типа Price.
Если ответ не является валидным JSON или Path ничему не соответствует, соответствующая переменная для этого пользователя не создается. Ошибка не отображается, и шаг Webhook все равно завершается нормально.

Использование данных ответа вебхука в вашем Journey

Тайм-аут, повторные попытки и неудачные запросы

Pushwoosh ожидает ответа до 10 секунд. Весь шаг Webhook, включая отправку запроса и обработку ответа, ограничен 30 секундами. Каждый “путешественник” запускает запрос один раз, автоматических повторных попыток нет.

Тайм-аут, сетевая ошибка или ответ, отличный от 2xx, приводят к тому, что “путешественник” выбывает из Journey на этом шаге, поскольку у элемента Webhook нет отдельной ветви для маршрутизации неудачных запросов. См. Ошибка запроса. Если вы не можете позволить себе терять “путешественников” на этом этапе, настройте вашу конечную точку так, чтобы она всегда возвращала ответ 2xx, а любое состояние сбоя помещайте в тело ответа, например, в виде значения, которое может быть получено с помощью сопоставления ответа.

Это касается только случаев, когда сам запрос не может быть выполнен. Ответ, который получен, но не может быть корректно сопоставлен, например, из-за невалидного JSON, неразрешенного Path или тела ответа более 64 КБ, не приводит к выбыванию “путешественника”. См. примечание в разделе Сопоставление ответа выше.

Протестируйте Webhook

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

Сохраните вашу конфигурацию

Нажмите Apply, чтобы сохранить конфигурацию вебхука.