Руководства и туториалы
6 мин чтения

Как настроить webhook-интеграцию с Trigly

Входящие и исходящие webhooks: события, payload, HMAC-подпись, retry policy. Интеграция Trigly с любым сервисом.

К
Команда Trigly
Руководство для разработчиков

Что такое webhooks и зачем они нужны

Webhooks (вебхуки) — это механизм уведомлений в реальном времени: когда в одной системе происходит событие, она автоматически отправляет HTTP-запрос в другую систему. В отличие от polling (опроса API каждые N секунд), webhooks работают мгновенно и не создают лишней нагрузки.

В контексте маркетинговой автоматизации webhooks нужны для:

  • Синхронизации с CRM: когда клиент открыл письмо — обновить карточку в CRM
  • Аналитики: передавать события доставки в BI-систему или Google Analytics
  • Автоматизации: запускать процессы в вашем бэкенде (обновление заказа, начисление бонусов)
  • Мониторинга: получать оповещения о проблемах доставки в Slack или Telegram
  • Интеграции с провайдерами: принимать статусы доставки от UniSender, SMS.ru, Telegram

Trigly поддерживает два типа webhooks: исходящие (Trigly отправляет данные вам) и входящие (внешние сервисы отправляют данные в Trigly).

Типы webhooks в Trigly

Исходящие (Trigly → ваш сервер)

Trigly отправляет POST-запрос на ваш URL, когда происходит одно из поддерживаемых событий:

Почтовые события:

  • email.sent — письмо передано почтовому серверу
  • email.delivered — письмо доставлено в почтовый ящик получателя
  • email.opened — получатель открыл письмо (трекинговый пиксель)
  • email.clicked — получатель кликнул ссылку в письме

SMS-события:

  • sms.sent — SMS отправлено провайдеру
  • sms.delivered — SMS доставлено на телефон

Кампании:

  • campaign.completed — кампания завершила отправку всем получателям

CDP-события:

  • customer.created — создан новый контакт
  • customer.updated — обновлён профиль контакта

Входящие (внешний сервис → Trigly)

Trigly принимает webhooks от провайдеров каналов доставки через публичные эндпоинты (не требуют JWT):

  • UniSender (POST /hooks/email/unisender) — bounce, complaint, unsubscribe. Trigly автоматически добавляет адрес в suppression list и помечает контакт как отписавшегося.
  • Универсальный bounce (POST /hooks/email/bounce) — hard bounce создаёт SuppressionEntry, spam complaint устанавливает unsubscribe.
  • Telegram (POST /hooks/telegram/{org_id}) — входящие сообщения, /start с deep link для привязки telegram_chat_id, нажатия callback-кнопок. Подробнее в руководстве по Telegram.
  • SMS.ru (POST /hooks/sms/status) — статусы доставки: 103 = доставлено, 104/105 = ошибка → автоматический retry.

Настройка исходящих webhooks

Шаг 1: Создайте endpoint на вашем сервере

Ваш сервер должен:

  1. Принимать POST-запросы
  2. Отвечать кодом 200 (или 2xx) в течение 10 секунд
  3. Проверять HMAC-подпись (рекомендуется)

Пример endpoint на Python (FastAPI):

from fastapi import FastAPI, Request, HTTPException
import hmac
import hashlib

WEBHOOK_SECRET = "your_secret_from_trigly"

@app.post("/webhook/trigly")
async def handle_trigly_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("X-Trigly-Signature")

    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        body,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        raise HTTPException(status_code=401)

    data = await request.json()
    event = data["event"]

    if event == "email.opened":
        # Обновить CRM
        pass
    elif event == "campaign.completed":
        # Отправить отчёт
        pass

    return {"status": "ok"}

Шаг 2: Зарегистрируйте webhook в Trigly

  1. Перейдите в раздел Кампании, затем Webhooks, нажмите "Создать"
  2. Укажите URL: https://your-server.com/webhook/trigly
  3. Выберите Events: типы событий, которые вас интересуют
  4. Trigly автоматически сгенерирует Secret для HMAC-SHA256 подписи
  5. Сохраните webhook. При желании можно привязать его к конкретной кампании (поле campaign_id) или оставить глобальным (null)

Webhook сохраняется в таблице campaign_webhooks и становится активным немедленно.

Шаг 3: Проверьте подпись

Каждый исходящий запрос от Trigly подписывается HMAC-SHA256 с использованием вашего Secret. Подпись передаётся в заголовке X-Trigly-Signature.

Алгоритм проверки:

  1. Прочитайте тело запроса как bytes
  2. Вычислите HMAC-SHA256(secret, body)
  3. Сравните с значением заголовка X-Trigly-Signature
  4. Если не совпадает — отклоните запрос (401/403)

Проверка подписи защищает от подделки: злоумышленник не может отправить фальшивый webhook на ваш URL, потому что не знает Secret.

Формат Payload

Все исходящие webhooks используют единый формат JSON:

{
  "event": "email.opened",
  "timestamp": "2026-03-20T10:30:00Z",
  "data": {
    "campaign_id": "550e8400-e29b-41d4-a716-446655440000",
    "customer_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Поля в data зависят от типа события:

  • email.* — содержат campaign_id, customer_id, message_id, для clicked также url
  • campaign.* — содержат campaign_id, total_sent, total_delivered, total_failed
  • customer.* — содержат customer_id, email, changes (для update)

Retry Policy

Trigly использует надёжную политику повторных попыток для исходящих webhooks:

  1. Первая попытка — немедленно при возникновении события
  2. Вторая попытка — через 30 секунд (exponential backoff)
  3. Третья попытка — через 2 минуты

Webhook считается неуспешным, если:

  • Сервер вернул код ответа не из диапазона 2xx
  • Сервер не ответил в течение 10 секунд (timeout)
  • Соединение не установлено (DNS error, connection refused)

Если webhook непрерывно fail более 10 раз подряд, Trigly автоматически деактивирует его (поле is_active = false) и отправляет уведомление администратору. Это защита от бесконечных retry на неработающий сервер.

Для реактивации: исправьте проблему на вашем сервере, перейдите в Кампании, затем Webhooks, и включите webhook обратно.

Входящие webhooks от провайдеров

Настройка UniSender

  1. В личном кабинете UniSender перейдите в Настройки уведомлений
  2. Укажите URL: https://your-trigly-domain.com/hooks/email/unisender
  3. Выберите события: bounce, complaint, unsubscribe
  4. UniSender начнёт отправлять уведомления в Trigly

При получении события Trigly автоматически:

  • bounce → создаёт SuppressionEntry в стоп-листе
  • complaint → suppression + устанавливает is_unsubscribed = true
  • unsubscribe → suppression + unsubscribe

Настройка Telegram

Настраивается автоматически при подключении бота в настройках каналов. Trigly вызывает setWebhook с URL /hooks/telegram/{org_id}. Подробнее: руководство по Telegram-боту.

Настройка SMS.ru

В личном кабинете SMS.ru укажите callback URL: https://your-trigly-domain.com/hooks/sms/status. SMS.ru будет отправлять статусы доставки (103 = доставлено, 104 = не доставлено, 105 = ошибка). При ошибке доставки Trigly создаёт запись в FailedMessage для автоматического retry.

Типичные ошибки

  1. Медленный обработчик. Если ваш сервер обрабатывает webhook дольше 10 секунд, Trigly считает это timeout и ретраит. Решение: принимайте webhook, сразу отвечайте 200, а обработку выполняйте асинхронно (через очередь).

  2. Отсутствие проверки подписи. Без верификации HMAC-SHA256 любой может отправить фальшивый POST на ваш URL. Всегда проверяйте X-Trigly-Signature.

  3. Не идемпотентный обработчик. Из-за retry один и тот же webhook может прийти дважды. Ваш обработчик должен быть идемпотентным — используйте message_id как ключ дедупликации.

  4. HTTP вместо HTTPS. Trigly передаёт данные клиентов в webhook payload. Используйте только HTTPS для защиты данных в transit.

  5. Игнорирование деактивации. Если webhook деактивирован (10+ последовательных ошибок), это значит, что вы теряете события. Настройте мониторинг на вашей стороне и быстро реагируйте на проблемы.

Best practices

  1. Быстрый ответ: отвечайте 200 мгновенно, обрабатывайте асинхронно
  2. Проверяйте подпись: HMAC-SHA256 верификация обязательна для production
  3. Дедупликация: используйте message_id для защиты от дублей при retry
  4. Логируйте всё: сохраняйте полный payload для отладки
  5. Мониторинг: настройте алерт на деактивацию webhook
  6. HTTPS only: никогда не используйте HTTP для production webhook URL

Ожидаемые метрики

  • Latency доставки webhook: менее 500ms (при стабильном сервере)
  • Success rate: 99%+ при правильной настройке
  • Retry utilization: менее 5% запросов требуют retry
  • Средний объём: 500-5000 webhook-событий в день на каждые 100 000 отправленных сообщений

FAQ

Можно ли отправлять webhooks в Slack или Telegram? Да, Trigly отправляет стандартный POST с JSON body. Для Slack создайте Incoming Webhook в настройках workspace. Для Telegram используйте промежуточный сервер (например, AWS Lambda), который преобразует payload в формат Telegram Bot API.

Как тестировать webhooks в разработке? Используйте сервисы типа webhook.site или ngrok для получения webhooks на локальный сервер. Создайте webhook в Trigly с URL от ngrok, запустите тестовую кампанию и проверьте входящие запросы.

Что произойдёт, если мой сервер был недоступен несколько часов? Trigly выполняет 3 retry с exponential backoff. Если все 3 попытки неуспешны, webhook-событие теряется. Для критичных интеграций рекомендуем дублировать данные через REST API — периодически запрашивать статусы кампаний и сообщений.

Готовы интегрировать Trigly с вашими системами? Создайте аккаунт и настройте первый webhook за 5 минут.

how-towebhookинтеграцияAPIразработка

Готовы автоматизировать маркетинг?

Email, Telegram, SMS, Push из одного окна. AI-копирайтинг. Предикция оттока.

Записаться на аудит

Читайте также

guides

Trigly для разработчика: API, SDK, вебхуки и интеграции

6 мин чтения
guides

Как интегрировать Trigly с Shopify: пошаговое руководство

7 мин чтения
guides

Как настроить API-ключи и JavaScript SDK в Trigly

6 мин чтения