Веб-хук

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

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

Как настроить элемент «Веб-хук»

Добавьте элемент «Веб-хук»

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

Рабочая область Customer Journey с выбранным шагом веб-хука Amplitude после элементов входа и ожидания

Назовите шаг «Веб-хук» и укажите URL-адрес и тип запроса

В поле НАЗВАНИЕ ШАГА введите название для веб-хука. Удобно называть веб-хуки в соответствии с сервисами, в которые они отправляют данные, или по сценарию использования.

Затем в поле URL укажите URL-адрес запроса, на который должны быть отправлены данные. Рядом с полем URL выберите тип запроса из выпадающего списка ТИП ЗАПРОСА: GET или POST.

Интерфейс настройки веб-хука, показывающий поле URL и выпадающий список ТИП ЗАПРОСА для выбора метода GET или POST

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

В разделе ЗАГОЛОВКИ установите тип контента.

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

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

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

При необходимости добавьте дополнительные заголовки, нажав + ДОБАВИТЬ ЗАГОЛОВОК. Вы можете удалить любой заголовок, нажав на значок «x» рядом с ним.

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

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

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

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

Откройте текстовый редактор и введите имя пользователя и пароль без пробелов, разделенные двоеточием. Например: <username>:<password>
Закодируйте эту строку в Base64.
Скопируйте полученную строку Base64 (например, <base64-encoded-string>).
В настройках веб-хука добавьте заголовок Authorization со значением: Basic <base64-encoded-string>. Убедитесь, что после слова “Basic” есть пробел.

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

Пометьте значение заголовка как секретное

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

Список заголовков веб-хука с замаскированным значением Authorization и неактивным значком глаза рядом с незамаскированным значением Content-Type с активным значком глаза

Автоматическое маскирование. Заголовки, названия которых похожи на учетные данные, маскируются автоматически, даже если вы не нажимаете на значок глаза. К ним относятся Authorization, Proxy-Authorization, Cookie, Set-Cookie, а также любые названия, содержащие token, secret, password, credential, auth или api-key/api_key/apikey (с дефисом, подчеркиванием или без разделителя).
Изменение замаскированного значения. Кликните в поле, где отображается ••••••••, и введите новое значение. Кнопки для отображения сохраненного значения нет. Значок глаза остается заблокированным, пока отображается маска. Чтобы убрать флаг секрета с заголовка, сначала введите новое значение, а затем нажмите на значок.
Переименование замаскированного заголовка. Переименование заголовка, значение которого в данный момент отображается как маска, очищает это значение. Введите его снова под новым именем. Переименование заголовка, который в данный момент содержит только что введенное вами значение, сохраняет это значение.

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

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

Пример:

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

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

Панель КОНСТРУКТОР ДАННЫХ позволяет вставлять динамическую информацию (например, данные о пользователе, устройстве, теге или событии) непосредственно в тело вашего JSON-запроса. С помощью динамических данных вы можете включать значения, специфичные для конкретного пользователя, проходящего через Journey.

Для этого:

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

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

Значения из запускающего события остаются привязанными к путешественнику на протяжении всего Journey, в том числе и после элемента «Задержка по времени». Они теряются только в том случае, если путешественник покидает Journey, например, при отменяющем событии, выходе или по завершении Journey. Если путешественник проходит через один и тот же шаг «Веб-хук» более одного раза, новый ответ перезаписывает значение, сопоставленное в прошлый раз.

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

{{tag:Language}}

Скопируйте макрос и вставьте его в тело JSON в разделе ДАННЫЕ.

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

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

Введите дополнительные плейсхолдеры вручную

Плейсхолдер — это макрос, который вы вводите вручную, а не генерируете из категории в КОНСТРУКТОРЕ ДАННЫХ. Панель КОНСТРУКТОР ДАННЫХ охватывает только данные Устройства, Тега и События. Вместо этого вводите эти плейсхолдеры непосредственно в разделы URL, ЗАГОЛОВКИ или ДАННЫЕ. Они не отображаются на панели:

Плейсхолдер	Значение
`{{application_code}}`	Код приложения, к которому принадлежит путешественник.
`{{traveler:id}}`	ID, который Pushwoosh присваивает этому путешественнику для данного прохождения Journey.
`{{journey:uuid}}`	UUID этого Journey.
`{{journey:name}}`	Название этого Journey.
`{{point:uuid}}`	UUID этого шага «Веб-хук».
`{{point:name}}`	НАЗВАНИЕ ШАГА этого шага «Веб-хук».
`{{event:name}}`	Название события, которое запустило вход этого путешественника в Journey.
`{{device:platform}}`	Платформа устройства, например `Android` или `iOS`.
`{{device:push_subscribed}}`	Подписан ли путешественник на пуш-уведомления — `true` или `false`.
`{{now}}`	Текущие дата и время, ISO 8601, UTC.
`{{now:unix_ms}}`	Текущее время в миллисекундах Unix.
`{{tags:all}}`	Все значения тегов для устройства путешественника в виде одного JSON-объекта. Используйте его без кавычек, например `"user_properties": {{tags:all}}`. Если взять его в кавычки, объект превратится в экранированную строку.

Сохраняйте тип плейсхолдера в теле JSON

Плейсхолдер в кавычках всегда становится строкой JSON, независимо от фактического типа значения. Тот же плейсхолдер без кавычек сохраняет собственный тип значения: число остается числом, true/false — булевым значением, а список — массивом JSON. Плейсхолдер без кавычек должен быть полным значением поля — "age": {{tag:Age}} сработает, а "note": prefix{{tag:Age}}suffix — нет, потому что все, что находится за пределами кавычек, записывается в том виде, в котором оно набрано, и лишние символы нарушают структуру JSON.

{
  "age": {{tag:Age}},
  "age_as_text": "{{tag:Age}}"
}

Здесь age отправляет числовое значение тега (34), а age_as_text — строку "34". Используйте тот вариант, который ожидает поле на принимающей стороне. Если у тега нет значения, плейсхолдер без кавычек все равно будет преобразован в пустую строку, а не в число или false. См. примечание в разделе Добавьте тело JSON-запроса.

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

Помимо отправки данных, шаг «Веб-хук» может сохранять значения из ответа, который возвращает ваш сервис. Вы даете каждому значению имя (Атрибут). Последующие шаги могут использовать это имя так же, как и другие значения ответа веб-хука. Например, можно установить тег с помощью элемента «Обновить профиль пользователя» или запланировать «Задержку по времени» на основе даты, возвращенной сервисом. Полный пример Journey см. в статье Использование данных ответа веб-хука в Journey.

Пример: CRM возвращает ID пользователя. Вы сохраняете его как Атрибут crm_user_id. Затем элемент «Обновить профиль пользователя» записывает его в тег.

Прежде чем что-либо сопоставлять, получите один пример ответа от сервиса. Попросите своего разработчика или откройте успешный вызов в Журнале вызовов после теста и посмотрите тело ответа. Вам понадобятся имена полей из этого ответа для построения Пути.

В разделе СОПОСТАВЛЕНИЕ ОТВЕТА нажмите + ДОБАВИТЬ СОПОСТАВЛЕНИЕ и заполните два поля для каждого значения, которое вы хотите сохранить:

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

Раздел сопоставления ответа с полями «Путь» и «Атрибут» и кнопкой «Добавить сопоставление» в настройках веб-хука

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

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

Установите Путь в data.user.id.
Установите Атрибут в crm_user_id.

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

«Разделение по условию» не может использовать их напрямую. Сопоставленные значения веб-хука не имеют типа. Сначала сохраните значение как тег, а затем создайте ветвление на основе этого тега. См. Сравнение значения веб-хука в «Разделении по условию».

Для одного поля Путь и значения работают следующим образом:

Записывайте имена объектов через точку: data.user.id.
Для списка используйте номер позиции, чтобы взять один элемент. Первый элемент имеет номер 0, поэтому results.0.code — это поле code первого элемента. Чтобы сопоставить каждый элемент в списке, см. Сопоставьте каждый элемент массива.
Нельзя сопоставить только некоторые элементы в списке. Для списка можно выбрать либо одну позицию, либо все элементы.
Pushwoosh сохраняет значение в том виде, в котором его отправил сервис (текст, число или true/false). Число 100 остается числом. Текст "100" остается текстом и не будет работать там, где Journey ожидает число. Для даты в элементе «Задержка по времени» сервис должен возвращать формат, который принимает «Задержка по времени». Десятичное число, например 19.99, может быть записано в тег типа Цена.
Если ответ не является валидным JSON или Путь не соответствует ни одному полю, этот атрибут не создается для данного пользователя. Шаг «Веб-хук» все равно завершается как обычно. Баннер с ошибкой не отображается. Проверьте тело ответа в Журнале вызовов и исправьте Путь, если значение отсутствует на последующих шагах.

Сопоставьте каждый элемент массива

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

Поставьте * в поле Путь там, где находится список. Pushwoosh извлечет значение из каждого элемента списка, а не только из одной позиции. Например, если список называется items и каждый элемент имеет item_name, установите Путь в items.*.item_name.

В разделе СОПОСТАВЛЕНИЕ ОТВЕТА нажмите + ДОБАВИТЬ СОПОСТАВЛЕНИЕ и заполните два поля как обычно, отметив список символом *:

Путь: местоположение значения в ответе, с * там, где находится список. Пример: items.*.item_name.
Атрибут: имя, которое вы будете использовать позже. То, что вы здесь напишете, определяет, как вы получите результаты:
- Включите {n} в имя, например item_{n}, чтобы получить каждый элемент как отдельное значение, пронумерованное с 1: item_1, item_2, item_3 и так далее. {n} может находиться в любом месте имени, например item_{n}_sku.
- Не используйте {n}, например item_names, чтобы объединить все элементы в одно значение, разделенное запятыми: Sofa, Lamp, Rug.

$Строка сопоставления ответа с Путем, установленным в items.*.item_name, и Атрибутом, установленным в item_{n}$

Позиции в списке Пути начинаются с 0 (items.0.item_name — это первый элемент). Имена атрибутов, созданные с помощью {n}, начинаются с 1 (item_1 — это тот же первый элемент). Это две разные нумерации.

Если вам нужен только один элемент из списка, используйте число в Пути вместо *, например items.0.item_name.

Пример

Если ваша CRM отвечает:

{
  "items": [
    { "item_name": "Sofa" },
    { "item_name": "Lamp" },
    { "item_name": "Rug" }
  ]
}

Установите Путь в items.*.item_name и Атрибут в item_{n}, чтобы получить три отдельных значения: item_1 — это Sofa, item_2 — Lamp, item_3 — Rug.
Вместо этого установите Атрибут в item_names, чтобы получить одно значение: item_names — это Sofa, Lamp, Rug.

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

«Обновить профиль пользователя»: сохранить значение в тег
«Задержка по времени»: ждать до даты из ответа
Динамический контент: персонализировать содержимое сообщения

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

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

Pushwoosh ожидает ответа до 10 секунд. Весь шаг «Веб-хук», включая отправку запроса и обработку ответа, ограничен 30 секундами.

Повторные попытки

При ответе 500, 502, 503 или 504, а также при сетевой ошибке, такой как сбой соединения, Pushwoosh повторяет запрос один раз, прежде чем прекратить попытки. Запрос, который истек по тайм-ауту, не повторяется — см. Что происходит при сбое запроса ниже. Любой другой ответ, отличный от 2xx, также не повторяется.

Ограничения скорости

Pushwoosh ограничивает количество запросов веб-хуков, которые аккаунт может отправлять в секунду. Лимит установлен значительно выше реальных пиков трафика, поэтому обычные Journey не затрагиваются. Всплеск, превышающий лимит, ожидает некоторое время, прежде чем завершиться ошибкой.

Период ожидания для эндпоинта

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

Что происходит при сбое запроса

Элемент «Веб-хук» не имеет отдельной ветки для неудачных запросов. Любое из следующих событий приводит к удалению путешественника из Journey на этом шаге:

Причина	Что вызывает
Заблокированный адрес эндпоинта	URL-адрес является частным, внутренним, loopback или link-local, включая эндпоинты метаданных облачных сервисов
Ограничение скорости	Превышен лимит запросов веб-хуков в секунду для аккаунта, и в течение короткого ожидания не освободилось место
Период ожидания для эндпоинта	Эндпоинт несколько раз подряд завершился с ошибкой, и Pushwoosh временно его пропускает
Тайм-аут	Нет ответа в течение 10 секунд, или шаг превысил свой 30-секундный лимит
Сетевая ошибка	Запрос не смог достичь эндпоинта
Ответ, отличный от 2xx	Эндпоинт вернул статус ошибки, который не подлежит повторной попытке, или был повторен один раз и снова завершился сбоем

См. Ошибка запроса.

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

Это относится к каждому шагу «Веб-хук», включая созданные ранее. Адрес эндпоинта, который теперь соответствует вышеуказанному правилу заблокированных адресов, начнет завершаться сбоем таким же образом.

В отличие от неудачного запроса, ответ, который получен, но не может быть корректно сопоставлен (например, невалидный JSON, неразрешенный Путь или тело ответа более 64 КБ), не приводит к удалению путешественника. См. примечание в разделе Сопоставьте данные ответа веб-хука с переменными выше.

Протестируйте веб-хук

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

Если заголовок все еще отображает сохраненную маску, Pushwoosh подставляет реальное, сохраненное значение для тестового запроса. Это значение никогда не отображается в вашем браузере.

Эта подстановка работает только для заголовка, уже сохраненного на этом конкретном шаге. Шаг, который вы еще не сохранили, или который вы только что скопировали, не имеет сохраненного значения за маской, поэтому Pushwoosh отправляет тестовый запрос без этого заголовка.

После успешного теста (или реального вызова) откройте Журнал вызовов, разверните строку и сравните тело ответа с каждым Путем. Поле должно существовать в точности так, как указано в Пути. Если запрос успешен, но на последующем шаге нет значения, обычно это означает, что Путь не соответствует ответу. Шаг «Веб-хук» не покажет ошибку в этом случае.

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

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

Журнал вызовов

Откройте вкладку Журнал вызовов в панели элемента, чтобы увидеть, что Pushwoosh фактически отправил для этого шага: время, пользователя, результат и длительность за последние 30 дней.

Фильтруйте по результату (Успешно, Ошибка HTTP, Нет ответа) или ищите по точному User ID или HWID. Нажмите на строку, чтобы развернуть ее и увидеть запрос (метод, URL и тело) и, в зависимости от результата, либо ответ (статус и тело), либо текст ошибки. Длительность охватывает весь шаг, включая время, затраченное на автоматическую повторную попытку.