Интеграция с входящими веб-хуками

Требуется помощь разработчика

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

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

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

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

Перед началом работы

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

1. Определите, что должен делать веб-хук. Веб-хук должен сопоставлять как минимум один тег, одно событие или и то, и другое. Чтобы вызвать событие, выберите существующее из вашего проекта (например, CheckoutSuccess) или создайте новое с атрибутами, которые вы хотите заполнить из входящих данных. Теги можно сопоставить с существующими тегами или создать на лету при настройке веб-хука.

2. Убедитесь, что ваш сторонний сервис может отправлять веб-хуки. Сервис должен иметь возможность отправлять HTTP POST-запрос на внешний URL, когда происходит интересующее вас событие, например, новый заказ или отправка формы.

3. Получите пример JSON-payload от вашего стороннего сервиса. Это небольшой пример данных, которые сервис отправляет при каждом событии. Он понадобится вам для сопоставления полей payload с тегами и атрибутами событий.

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

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

1. В вашем аккаунте Pushwoosh перейдите в Настройки → Интеграции → Входящие веб-хуки и нажмите Настройки.

2. Нажмите Создать веб-хук, чтобы открыть экран настройки: Вставьте пример payload слева, Настройка веб-хука справа.

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

Сопоставление входящих данных

1. В поле Вставьте пример payload вставьте пример JSON-payload от вашего стороннего сервиса. Pushwoosh извлечет поля и загрузит их в выпадающие списки полей payload.

Примечание

Если вы позже обновите payload, нажмите Reload select options, чтобы обновить выпадающие списки. Это сбросит ваше текущее сопоставление полей. Вам нужно будет заново сопоставить поля.

Пример payload:

{
  "id": "12345",
  "email": "jane@example.com",
  "phone": "+15551234567",
  "loyalty_tier": "gold",
  "order_number": "ORD-001",
  "price": 99.99
}

2. В поле Идентифицировать пользователей по, выберите, как Pushwoosh должен сопоставлять входящий запрос с пользователем:

• User ID: ваш внутренний идентификатор, присвоенный пользователю в системе.
• Email: сопоставление по адресу электронной почты.
• Phone: сопоставление по номеру телефона.
• HWID: идентификатор устройства, браузера или электронной почты.
• Token: сопоставление по push-токену устройства.

3. В поле Поле payload выберите поле, содержащее соответствующее значение.

4. Необязательно: включите флажок под полем Поле payload, чтобы автоматически создавать нового пользователя, если совпадение не найдено, вместо того чтобы отклонять запрос. Его метка соответствует вашему выбору идентификатора, например, Создать новый User ID, если совпадение не найдено или Создать новый Email, если совпадение не найдено. Флажок отключен для HWID и Token, так как Pushwoosh не может создать идентификатор устройства, браузера или push-токена до фактической сессии SDK.

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

Добавление тегов в профиль

Используйте Добавить теги в профиль, чтобы сохранять значения из payload в качестве тегов в профиле сопоставленного пользователя. Заполняйте данные профиля, такие как уровень тарифа или город, для лучшей сегментации.

1. Нажмите + Добавить тег.
2. В поле Имя тега выберите существующий тег из списка или введите новое имя. Pushwoosh покажет Создать: <имя>, чтобы подтвердить, что он создаст новый тег.
3. Если вы выбрали существующий тег, поле Тип покажет его тип и не может быть изменено. Если вы создали новый тег, откройте Тип и выберите его тип данных. Pushwoosh сохранит его как тег этого типа для конкретного пользователя.
4. В поле Поле payload выберите поле из вашего примера payload, которое содержит значение.
5. Повторите шаги 1–4 для каждого тега, который вы хотите заполнить.

Чтобы удалить строку, нажмите ×.

Запись события

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

1. В поле Событие выберите событие Pushwoosh, которое нужно вызвать.
2. Нажмите + Добавить атрибут.
3. В поле Атрибут события выберите существующий атрибут выбранного события из списка или введите новое имя. Pushwoosh покажет Создать: <имя>, чтобы подтвердить, что он создаст новый атрибут.
4. Если вы выбрали существующий атрибут, поле Тип покажет его тип и не может быть изменено. Если вы создали новый атрибут, откройте Тип и выберите его тип данных.
5. В поле Поле payload выберите поле из вашего примера payload, которое содержит значение.
6. Повторите шаги 2–5 для каждого атрибута, который вы хотите заполнить.

Чтобы удалить строку, нажмите ×.

Включение и подключение

1. Когда конфигурация завершена, нажмите Включить веб-хук. Откроется окно URL веб-хука.

Требуется помощь разработчика

Следующие шаги требуют доступа к настройкам веб-хуков вашего стороннего сервиса. Поделитесь URL и Secret с вашей командой разработчиков.

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

3. Скопируйте Secret и вставьте его в ваш сторонний сервис в качестве значения заголовка Authorization. Значение включает префикс Bearer, поэтому используйте его как есть. Pushwoosh отклоняет любой запрос, в котором этот заголовок отсутствует или не совпадает.

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

После включения веб-хука он появится в списке веб-хуков со статусом «включен» и начнет принимать запросы.

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

В списке входящих веб-хуков отображаются все веб-хуки в вашем проекте.

Каждая строка показывает:

• Имя: имя веб-хука.
• Статус: Включен или Отключен.
• Получено: общее количество входящих запросов, полученных веб-хуком.
• Последнее изменение: когда веб-хук был изменен в последний раз.

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

Откройте меню строки, чтобы:

• Редактировать настройки: открывает конфигурацию веб-хука, чтобы вы могли изменить имя, событие, сопоставление полей и идентификацию пользователя.
• Копировать URL: открывает окно URL веб-хука с URL и Secret, чтобы вы могли скопировать их снова.
• Журнал активности: открывает журнал запросов для этого веб-хука.
• Удалить: удаляет веб-хук из списка.

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

Просмотр журнала активности

В журнале активности отображаются все входящие запросы для выбранного веб-хука.

Сводная панель

Вверху просмотрите сводку за последние 24 часа:

• Всего обращений: общее количество полученных входящих запросов.
• Предупреждения: запросы, в которых пользователь был идентифицирован (или создан), но как минимум одно настроенное сопоставление тега или события не удалось применить.
• Сбои: запросы, которые не были обработаны вообще, например, из-за неверного секрета или отсутствия поля идентификатора. Неудачный запрос не останавливает веб-хук. Pushwoosh продолжает принимать и обрабатывать последующие запросы.

Причина сбоя	Что это значит
Аутентификация отклонена	Общий секрет не соответствует конфигурации веб-хука. Если пять последовательных запросов завершатся с этой ошибкой, Pushwoosh отправит вам уведомление. Обновите секрет, чтобы возобновить работу. Повторная активация не требуется.
Отсутствует поле идентификатора пользователя	Поле payload, сопоставленное для идентификации пользователя, отсутствует в запросе.

Записи запросов

Каждая запись показывает значок статуса, идентификатор пользователя (например, User ID или Email), временную метку запроса и галочку для каждой возможности, которую вы настроили на веб-хуке: User ID (или ваш выбранный идентификатор), Теги и Событие. Галочка означает, что эта часть запроса была успешно применена; запрос может показывать смесь отмеченных и неудавшихся элементов. Нажмите Показать, чтобы развернуть полный полученный JSON-payload.

Просмотр событий и тегов, вызванных веб-хуком, в User Explorer

Когда запрос веб-хука успешно обработан, Pushwoosh записывает результат для сопоставленного (или вновь созданного) пользователя в User Explorer. Где появится событие, зависит от того, как вы идентифицировали пользователя:

• User ID, Email или Phone: событие записывается в профиль пользователя. Откройте пользователя и перейдите в Историю событий.
• HWID: событие записывается на соответствующем устройстве. Откройте пользователя, найдите устройство в Активных устройствах пользователя и перейдите на его вкладку История событий.

Найдите событие по имени и разверните его, чтобы увидеть сопоставленные атрибуты (например, price или products) и атрибут __webhook с ID веб-хука. Сопоставленные теги появляются у того же пользователя на вкладке Обзор пользователя, независимо от типа идентификатора.

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

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