Подписка на события рассылок по аудитории и push-отправок — База знаний

Вебхуки позволяют получать в свою систему уведомления о событиях, которые происходят в Fasttrack — без необходимости регулярно опрашивать API (polling). Fasttrack сам отправит POST-запрос на указанный адрес в момент, когда событие произошло.

Зачем это нужно

Представим интернет-магазин косметики, который использует Fasttrack как комплексную платформу: чат-бот, сценарии вебинаров, e-com каталог, рассылки по аудитории и триггерные push-отправки. Вебхуки в этой картине закрывают отдельную задачу — передачу статусов рассылок и push-отправок во внешние системы магазина.

Статус и реакции на рассылку в CRM. Магазин раз в неделю отправляет рассылку по аудитории с новинками и акциями. Через вебхук магазин видит в своей CRM в реальном времени, кому сообщение отправлено, доставлено, а кому нет — независимо от канала рассылки. По статусу «не доставлено» можно автоматически предложить клиенту альтернативный канал связи или пометить контакт для последующей чистки базы. Туда же попадают реакции: если в рассылке про новую тушь для ресниц есть кнопка «Заказать со скидкой», магазин получает событие о нажатии в момент клика — и может сразу запустить персональный сценарий оформления заказа для этого клиента, не дожидаясь, пока он сам напишет в чат. А переходы по ссылке на лендинг новой линейки помогают посчитать реальный CTR рассылки прямо в CRM, без ручной выгрузки статистики.
Статус персональной push-отправки. Клиентка добавила в «Избранное» крем, который закончился на складе. Когда товар снова в наличии, магазин отправляет ей персональное сообщение об этом через мессенджер. Через вебхук магазин отслеживает статус этой конкретной отправки — если сообщение не дошло, можно автоматически повторить отправку по другому контакту клиента (например, на другой номер телефона) или переключиться на иной канал связи.
Данные для BI-аналитики. Вместо того чтобы вручную выгружать статистику по рассылкам и push-отправкам из интерфейса Fasttrack, магазин настраивает приём всех событий в свою BI-систему (или собственное хранилище данных) через вебхуки. На основе этих данных строятся собственные отчёты и графики — например, динамика доставляемости по каналам или конверсия рассылок в клики.

Как подключить

Откройте настройки проекта → раздел «Вебхуки».
Заполните поле Endpoint URL — адрес, на который будут приходить события.
Включите тумблеры напротив нужных событий.
Нажмите «Сохранить изменения».

Важно: один Endpoint URL обслуживает все включённые события одновременно. На стороне вашей системы нужна логика разбора входящего запроса по полю event_type, чтобы отличать одно событие от другого.

Формат запроса

Все события приходят в едином конверте:

{
 "event_type": "<тип события>",
 "payload": { ... },
 "timestamp": <int>
}

event_type — тип события. Указывается в нижнем регистре через нижнее подчёркивание (snake_case) и не совпадает буквально с названием события в интерфейсе.
payload — данные события, структура зависит от типа.
timestamp — время отправки вебхука, unix-время в миллисекундах.

Соответствие названия в интерфейсе и значения event_type:

Событие в интерфейсе	`event_type` в запросе
MAILING_STATE	`mailing_state`
MAILING_REACTION	`mailing_reaction`
PUSH_MESSAGE_STATE	`push_message`
LEGACY_WHATSAPP_STATE	устаревший формат, см. ниже

Осторожно: формат значений статусов различается между событиями — где-то используется ВЕРХНИЙ_РЕГИСТР, где-то snake_case. Сверяйтесь с примерами ниже при разработке интеграции.

Справочник событий

MAILING_STATE — статус сообщения в рассылке по аудитории

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

{
 "event_type": "mailing_state",
 "payload": {
 "chat": {
    "uuid": "<uuid>"
},
 "profile": {
    "uuid": "<uuid>"
},
 "mailing": {
    "uuid": "<uuid>"
},
 "message": {
    "state": "SENT | DELIVERED | UNDELIVERED | READ"
}
 },
 "timestamp": <int>
}

Параметры

Параметр	Описание
`payload.chat.uuid`	Идентификатор чата
`payload.profile.uuid`	Идентификатор профиля клиента
`payload.mailing.uuid`	Идентификатор рассылки
`payload.message.state`	Текущий статус сообщения

Возможные значения message.state

Статус	Описание
`SENT`	Сообщение отправлено
`DELIVERED`	Сообщение доставлено
`UNDELIVERED`	Сообщение не доставлено
`READ`	Сообщение прочитано

MAILING_REACTION — реакция на сообщение в рассылке по аудитории

Сообщает о действии получателя с отправленным сообщением рассылки.

{
 "event_type": "mailing_reaction",
 "payload": {
 "chat": {
    "uuid": "<uuid>"
},
 "profile": {
    "uuid": "<uuid>"
},
 "mailing": {
    "uuid": "<uuid>"
},
 "message": {
    "reaction": "button_clicked | url_clicked | replied"
}
 },
 "timestamp": <int>
}

Параметры

Параметр	Описание
`payload.chat.uuid`	Идентификатор чата
`payload.profile.uuid`	Идентификатор профиля клиента
`payload.mailing.uuid`	Идентификатор рассылки
`payload.message.reaction`	Тип реакции на сообщение

Возможные значения message.reaction

Реакция	Описание
`button_clicked`	Нажатие на кнопку в сообщении
`url_clicked`	Переход по ссылке (по кнопке или в тексте сообщения)
`replied`	Ответное сообщение от получателя

PUSH_MESSAGE_STATE — статус push-отправки

Сообщает об изменении статуса отправки персонального сообщения, которое было отправлено по API или запланировано к отправке через сценарий бота.

По одной отправке событие может приходить несколько раз — по мере смены статуса. Все события одной отправки объединены общим payload.uuid.

{
 "event_type": "push_message",
 "payload": {
 "uuid": "<uuid>",
 "chat": {
    "uuid": "<uuid>",
    "platform": "<str>"
},
 "profile": {
    "uuid": "<uuid>",
    "phone_number": "<str>",
    "external_id": null
},
 "state": {
    "code": "IN_PROCESS | SENT | UNDELIVERED | DELIVERED | READ",
    "detail": null
},
 "created_at": <int>,
 "sent_at": null,
 "delivered_at": null
 },
 "timestamp": <int>
}

Параметры

Параметр	Описание
`payload.uuid`	Уникальный идентификатор push-отправки. Одинаковый во всех событиях одной цепочки
`payload.chat.uuid`	Идентификатор чата
`payload.chat.platform`	Канал доставки (например, Telegram, Vkontakte)
`payload.profile.uuid`	Идентификатор профиля клиента
`payload.profile.phone_number`	Номер телефона клиента
`payload.profile.external_id`	Внешний идентификатор клиента из вашей системы, если передавался
`payload.state.code`	Текущий статус отправки
`payload.state.detail`	Дополнительная информация о статусе
`payload.created_at`	Время создания отправки
`payload.sent_at`	Время фактической отправки. Заполняется при статусе `SENT` и позднее
`payload.delivered_at`	Время доставки. Заполняется только при статусе `DELIVERED`

Возможные значения state.code

Статус	Описание	Доступность
`IN_PROCESS`	Отправка в процессе	Все каналы
`SENT`	Отправлено	Все каналы
`UNDELIVERED`	Не доставлено	Все каналы
`DELIVERED`	Доставлено	Только WhatsApp
`READ`	Прочитано	Только WhatsApp

Осторожно: полный набор статусов зависит от канала доставки (payload.chat.platform). Для WhatsApp дополнительно доступны статусы DELIVERED и READ; для остальных каналов финальными статусами являются SENT и UNDELIVERED.

Пример цепочки событий одной отправки

Отправка проходит через несколько статусов, каждый оформляется отдельным вебхуком с одним и тем же payload.uuid:

Отправка создана и обрабатывается — state.code: "IN_PROCESS", sent_at и delivered_at ещё null.
Отправка выполнена — state.code: "SENT", заполняется sent_at. Поле created_at при этом не меняется.

LEGACY_WHATSAPP_STATE

Устаревший формат события о статусе отправки в WhatsApp. Оставлен для обратной совместимости с ранними интеграциями.

Для новых интеграций используйте актуальное событие MAILING_STATE.