Исходящие постбэки

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

События Telegram

Первый раздел пересылает исходные обновления Telegram, а не рекламные конверсии. Укажите адрес назначения и выберите business_message (личные сообщения Telegram Business), business_connection, chat_join_request и/или chat_member (вступления, выходы и изменения статуса).

Настройки относятся к боту в рамках всего аккаунта, а не только к одному сайту. Адрес назначения получает содержимое сообщений и идентификационные данные Telegram из выбранных обновлений. Указывайте только тот сервер, который вы контролируете. История отправок относится к сайту, на котором адрес назначения был настроен впервые.

Новые универсальные механизмы пересылки отправляют JSON с полем update_id и выбранным объектом обновления Telegram без изменений. Они используют описанные ниже заголовки подписи и доставки X-AdTarget-*, сохраняемую очередь и до шести попыток отправки. Повторные идентификаторы обновлений Telegram исключаются как дубликаты в пределах сохраняемой истории отправок. Такая пересылка не создаёт события Lead, Purchase или другие рекламные события.

Существующая интеграция TSA / Ross

Существующая пересылка TSA отображается с текущим URL и включёнными типами событий Telegram. Она сохраняет адрес назначения /telegram/proxy, аутентификацию через X-Forward-Secret / X-Forward-Timestamp, исходные данные Telegram с дополнительными сведениями об источнике и действующую политику повторных попыток. Она не использует универсальный протокол HMAC или новые переключатели конверсий. Она остаётся единственным отправителем для TSAWelcomeBot; автоматическое добавление второго отправителя, смена секрета, повторная отправка истории или миграция получателя не выполняются. Предыдущие отправки этой интеграции не добавляются задним числом в общую историю отправок.

Эта защищённая существующая интеграция доступна в редакторе только для просмотра. При включении новой пересылки для других ботов она намеренно не заменяется.

События конверсий (необязательно)

Раскройте раздел События конверсий — необязательно, чтобы пересылать новые записи конверсий AdTarget, включая конверсии, полученные через входящий REST API. Эти переключатели не управляют описанной выше пересылкой Telegram.

Настройка отправки конверсий

Откройте Сайт → Настройки → Постбэки, укажите один публичный HTTPS-адрес, выберите типы событий и включите отправку. Сохраните настройки, скопируйте секрет подписи, который показывается один раз, затем выберите Отправить тест. Обычно очередь начинает отправку в течение одной минуты. Изменять настройки может только владелец сайта; предварительный просмотр для администратора доступен только для чтения.

Поддерживаемые типы: Lead, Purchase, CompleteRegistration, Subscribe, Contact и Custom. При выборе Custom включаются все пользовательские имена событий; различайте их по полю data.customEventName. Это типы конверсий, а не просмотры страниц, исходные события вступления/выхода Telegram или производные бизнес-этапы, такие как QFTD. При вступлении используется событие конверсии, настроенное для соответствующего канала.

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

Сохранение настроек отменяет ожидающие отправки из предыдущей конфигурации. Отключение останавливает отправки в очереди; уже выполняющийся запрос может завершиться. Используйте публичное доменное имя, разрешаемое в IPv4-адрес, с HTTPS на порту 443. Частные адреса и перенаправления блокируются.

Запрос

AdTarget отправляет запрос POST с заголовком Content-Type: application/json:


{
  "version": 1,
  "event": "Purchase",
  "occurredAt": 1789300000000,
  "data": {
    "conversionId": "conversion-id",
    "websiteId": "atid_example",
    "telegramUserId": 123456789,
    "value": 97,
    "currency": "EUR",
    "contentName": "VIP"
  }
}

occurredAt — время Unix в миллисекундах. Необязательные поля опускаются, если значения отсутствуют. Имена, адреса электронной почты, номера телефонов, IP-адреса, ключи API и учётные данные рекламных платформ не включаются. Тест использует event: "test" и пример сообщения; он не создаёт конверсию и ничего не отправляет вашим рекламным пикселям.

Проверка подлинности

Храните секрет на своём сервере. Проверяйте следующие заголовки:

X-AdTarget-Delivery-Id: сохраняется при повторных попытках; используйте его для исключения повторной обработки.
X-AdTarget-Timestamp: время Unix в секундах, обновляемое при каждой попытке.
X-AdTarget-Signature: префикс sha256=, за которым следует шестнадцатеричное значение HMAC-SHA256 от timestamp + "." + rawRequestBody, подписанное вашим секретом.

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

Надёжность

Доставка выполняется по принципу «как минимум один раз», а не «ровно один раз». Тайм-аут после принятия события вашим сервером может привести к дубликату. Всего выполняется до шести попыток с увеличивающимися задержками. HTTP-перенаправления и другие ответы со статусом вне диапазона 2xx считаются ошибками. На разрешение DNS отводится до пяти секунд, на HTTP-запрос — до десяти секунд.

История отправок показывает последние 50 запросов, попытки, статус и HTTP-код. Завершённые записи истории хранятся 30 дней. Неудачный постбэк не меняет ответ входящего API или статус отправки конверсии в Meta/TikTok/Snapchat. Избегайте циклов: не отправляйте каждый исходящий постбэк обратно в AdTarget как новое входящее событие.