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

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

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

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

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

Определите, какое событие Pushwoosh должен вызывать веб-хук. Выберите существующее событие из вашего проекта, которое вы хотите вызывать из стороннего сервиса. Например, CheckoutSuccess. Если у вас еще нет подходящего события, создайте его с атрибутами, которые вы хотите заполнить из входящих данных.
Убедитесь, что ваш сторонний сервис может отправлять веб-хуки. Сервис должен иметь возможность отправлять HTTP POST-запрос на внешний URL-адрес, когда происходит интересующее вас событие, например, новый заказ или отправка формы.
Получите пример полезной нагрузки (payload) в формате JSON от вашего стороннего сервиса. Это небольшой пример данных, которые сервис отправляет при каждом событии. Он понадобится вам для сопоставления полей полезной нагрузки с атрибутами событий Pushwoosh.

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

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

Страница интеграций с карточкой «Входящие веб-хуки» и кнопкой «Настройки» для открытия конфигурации веб-хука

Нажмите Создать веб-хук, чтобы открыть мастер настройки.

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

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

Экран настройки веб-хука с выпадающим списком событий Pushwoosh для выбора события, которое будет срабатывать при входящем запросе

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

Пример полезной нагрузки:

{
  "user_id": "12345",
  "email_address": "jane@example.com",
  "mobile": "+15551234567",
  "purchase_date": "2024-03-15",
  "order_number": "ORD-001",
  "price": 99.99,
  "payment_state": "success"
}

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

User ID: сопоставление по внутреннему идентификатору пользователя в Pushwoosh.
Email: сопоставление по адресу электронной почты.
Phone: сопоставление по номеру телефона.
HWID: сопоставление по идентификатору устройства, браузера или электронной почты.

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

Выпадающие списки «Идентифицировать пользователей по» и «Поле полезной нагрузки» с подсказкой для User ID и HWID на экране сопоставления входящих данных

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

Атрибут события: имя атрибута в Pushwoosh. Выберите из атрибутов, определенных для этого события.
Поле полезной нагрузки: поле из входящей полезной нагрузки, содержащее значение.

Например, сопоставьте email с email_address, total с price и order_id с order_number.

Строки сопоставления атрибута события и поля полезной нагрузки с примером полезной нагрузки и кнопкой «Перезагрузить опции выбора»

Нажмите + Добавить атрибут, чтобы добавить строку. Нажмите ×, чтобы удалить ее.

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

Скопируйте значения и вставьте их в настройки веб-хука вашей внешней системы:

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

Окно URL веб-хука, показывающее поля URL и Secret с кнопками копирования для настройки внешней системы

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

Окно URL веб-хука с URL, секретным ключом и примером запроса curl для настройки внешней системы

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

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

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

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

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

Список входящих веб-хуков с поиском, фильтрами статуса, столбцами таблицы и открытым меню действий для строки

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

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

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

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

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

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

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

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

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

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

Причина сбоя

Что это значит

Аутентификация отклонена

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

Отсутствует поле идентификатора пользователя

Поле полезной нагрузки, сопоставленное для идентификации пользователя, отсутствует в запросе.

Журнал активности со сводкой «Обращения», «Успешно», «Неудачно» и записями запросов, показывающими значок статуса и полезную нагрузку JSON

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

Каждая запись показывает идентификатор пользователя (например, User ID или Email), значок Успешно или Неудачно, временную метку запроса и предварительный просмотр полученной полезной нагрузки JSON. Нажмите Показать, чтобы развернуть полную информацию о запросе.

Запись запроса в журнале активности с идентификатором пользователя, значком «Успешно» или «Неудачно», временной меткой, полезной нагрузкой JSON и кнопкой «Показать»

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

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

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

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

Вкладка «История событий» в User Explorer, показывающая событие от входящего веб-хука с развернутыми атрибутами, включая ID __webhook и сопоставленные поля полезной нагрузки

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

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