Перейти к основному содержимому

Вебхуки

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

🚀 Зачем использовать вебхуки вместо обычных API-запросов?​

  • Снижение нагрузки на серверы (Event-Driven): Заменяют постоянные опросные запросы (polling) к API Sailplay. Ваш бэкенд получает данные только тогда, когда в системе происходит реальное событие.
  • Эффективное кэширование: Позволяют хранить профиль и баланс пользователя в кэше мобильного приложения/сайта и сбрасывать его строго в момент получения вебхука об изменениях.
  • Реальное время (Real-Time UX): Обеспечивают мгновенную реакцию интерфейсов и сервисов.
  • Бесшовная интеграция: Легко связывают Sailplay с внешними CRM, DWH, Telegram-ботами и др.системами
Отправка сообщений в Telegram, VK и мессенджеры

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

Однако обращаем ваше внимание, что это не является целевым архитектурным решением. Такой подход может служить только временным решением (MVP) в случаях, когда прямая интеграция ограничена или другие ограничения.

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

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

Ниже представлены примеры использования вебхуков, которые ярко иллюстрируют их пользу, экономию ресурсов и улучшение пользовательского опыта (UX):

1. Инвалидация и актуализация кэша​

  • 🔴 Проблема: Мобильное приложение или сайт при каждом открытии запрашивает профиль пользователя (баланс, статус, скидку). Это создает огромную нагрузку на API и увеличивает время загрузки экрана.
  • 🟢 Решение: Приложение кэширует профиль клиента. При изменении данных в Sailplay отправляется вебхук, и бэкенд сбрасывает кэш только тогда, когда данные реально изменились.

2. Автоматизация сценариев в CRM / Helpdesk​

  • 🔴 Проблема: Клиент перешел на новый VIP-уровень или его баланс упал до нуля. Менеджеры узнают об этом только при ручной проверке карточки.
  • 🟢 Решение: Вебхук об изменении статуса автоматически создает задачу в CRM: «Позвонить VIP-клиенту» или «Отправить подарок».

3. Обогащение аналитики (CDP / DWH)​

  • 🔴 Проблема: Данные о поведении хранятся в системе лояльности. Для сквозной аналитики приходится раз в сутки выгружать тяжелые CSV-файлы через API.
  • 🟢 Решение: Изменения стримятся напрямую в хранилище данных (DWH) через вебхук, позволяя строить Real-Time отчеты.
Ограничения и риски: Запросы внутрь API Sailplay (Зацикливание)

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

  • Риск зацикливания (рекурсии): Если вызванный метод API сгенерирует новое событие в системе, это вызовет повторный вебхук и приведет к бесконечной рекурсии запросов.
  • Перегрузка сервиса: Подобная закольцованная логика создает высокую некорректную нагрузку на систему и может привести к деградации производительности или блокировке аккаунта.

⚙️ Типы вебхуков​

В платформе поддерживается два типа вебхуков:

  1. Системные вебхуки — настраиваются через административную панель (поддерживают только события изменения баланса).
  2. Пользовательские вебхуки — настраиваются в личном кабинете Sailplay в рамках триггерных цепочек (по событиям и тегам).

1. Системные вебхуки​

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

Типы системных хуков​

  • CustomerBalanceUpdateHook
    Выполняет последовательный поиск пользователя по идентификаторам в следующем порядке:

    1. oid (внутренний ID)
    2. phone (номер телефона)
    3. email (электронная почта)

  • CustomerBalanceUpdateByPhoneHook
    Использует для идентификации пользователя только номер телефона.

    Важно: В текущей версии вебхука поле с номером телефона передается как phone (ранее именовалось mobile_phone).

Конфигурация и пример запроса​

Пример настроек вызова внешней системы:

{
  "url": "https://loyalty.roy.ru/api/v2/user/webhook",
  "method": "PUT",
  "headers": {
    "X-Service-Key": "111111-39b2-19d3-8696-4245118cfdc7",
    "Content-Type": "application/json"
  }
}

Формат передаваемых данных (Payload)​

Пример тела запроса (JSON):

{
  "phone": "<номер телефона клиента>",
  "bonusPointsType": "NLP",
  "bonusPoints": 723,
  "unconfirmedBonusPoints": 0,
  "touchPoint": "129"
}

Логика формирования тела запроса (Backend):​

result = {
    'touchPoint': self.context.get('touchPoint', 'null'),
    'bonusPoints': balance['confirmed'],
    'unconfirmedBonusPoints': balance['unconfirmed'],
    'bonusPointsType': 'NLP',
}

Описание полей payload:​

ПолеТипОписание
phoneStringНомер телефона клиента
bonusPointsTypeStringТип бонусных баллов (по умолчанию "NLP")
bonusPointsNumberПодтвержденный (активный) баланс бонусов
unconfirmedBonusPointsNumberНеподтвержденный (неактивный) баланс бонусов
touchPointStringИдентификатор точки касания / магазина

2. Пользовательские вебхуки​

Пользовательские вебхуки настраиваются в личном кабинете Sailplay в визуальном редакторе триггерных цепочек. Блок «Вебхук» используется для отправки запросов на внешний ресурс или к API Sailplay при наступлении заданного события (например, присвоение тега об измененеии статуса подписки).

[ Триггер: Изменение статуса подписки ] ➔ [ Блок: Вебхук ] ➔ [ Внешний сервис / API ]

Параметры настройки блока «Вебхук»:​

  • Описание — название блока, которое отображается при просмотре всей триггерной цепочки (например, «Выдаём клиенту промокод»).
  • Метод запроса и URL:
    • Поддерживаемые HTTP-методы: GET, POST, PUT, PATCH, DELETE.
    • URL внешнего сервиса или API Sailplay (например, https://api.sailplay.ru/api/v2/promocodes/issue).
  • Параметры запроса (Payload):
    • Поддерживаемые форматы: Form URL encoded, Multipart Form, JSON, Text.
    • В форматах Form URL encoded и Multipart Form доступен выбор переменных из списка (например, ${target_phone}) и изображений из менеджера контента.
  • Аутентификация:
    • Поддерживаемые типы: No Auth (по умолчанию), Basic Auth, Digest Auth.
  • Заголовки запроса (Headers):
    • Возможность добавления пользовательских HTTP-заголовков (например, Content-Type, Accept и др.).