Каналы уведомлений

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

Доступны два типа каналов: вебхук и Telegram.

Вебхук-каналы отправляют HTTP POST запрос с JSON payload на ваш эндпоинт при обнаружении отслеживаемой транзакции.

curl -X POST "https://api.vilna.io/v1/channels" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Webhook",
    "config": {
      "kind": "webhook",
      "url": "https://api.example.com/webhooks/vilna",
      "headers": {
        "Authorization": "Bearer your-secret-token"
      }
    }
  }'

Каждая доставка вебхука отправляет TransactionAlertPayload с четырьмя полями верхнего уровня:

{
  "event_id": "f47ac10b-58cc-5372-a567-0e02b2c3d479",
  "item": { /* Объект транзакции */ },
  "references": {
    "tokens": { /* GID токена -> детали токена */ },
    "blockchains": { /* GID сети -> детали блокчейна */ },
    "addresses": { /* адрес -> метка */ }
  },
  "is_test_message": false
}

• event_id - UUIDv5, совпадает со значением заголовка X-Webhook-Event-Id. Стабилен между повторными доставками и входит в подписываемое тело, поэтому защищён от подделки. Используйте его для дедупликации.
• item - полный объект транзакции, включая события (переводы, комиссии) и записи активности с дельтами по адресам.
• references - справочные данные для токенов, блокчейнов и адресов, упомянутых в транзакции. Дополнительные API-вызовы для получения названий и символов не нужны.
• is_test_message - true, если payload был отправлен тестовым действием, false для реальных блокчейн-событий.

Каждый вебхук-запрос содержит четыре заголовка:

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

Telegram-каналы отправляют форматированные сообщения в чат Telegram через Bot API.

1. Создайте бота через @BotFather и сохраните токен бота.
2. Добавьте бота в целевой чат (группу, канал или личные сообщения).
3. Получите ID чата (используйте @userinfobot или Telegram API getUpdates).

curl -X POST "https://api.vilna.io/v1/channels" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ops Alerts",
    "config": {
      "kind": "telegram",
      "bot_token": "123456789:ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789",
      "chat_id": -1001234567890,
      "language": "en",
      "thread_id": 0
    }
  }'

Поля конфигурации:

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

Получите логи с помощью GET /channels/{channel_id}/logs. Ответ - постраничный список, отсортированный по убыванию даты доставки.

Параметры запроса:

У каждой записи лога есть поле is_test - true для доставок, инициированных тестовым действием, false для продакшн-событий.

# Получить неудачные доставки для канала
curl "https://api.vilna.io/v1/channels/{channel_id}/logs?is_success=false" \
  -H "X-Api-Key: your-api-key"

Когда использовать логи доставки:

• После создания и тестирования канала убедитесь, что тестовая доставка зафиксирована как успешная.
• Если уведомления перестали приходить, запросите логи с is_success=false, чтобы увидеть HTTP-коды ответов и детали ошибок вашего эндпоинта.
• Используйте поле is_test в записях лога, чтобы отделить тестовый трафик от продакшн-доставок.

Каналы проходят простой жизненный цикл: создание, тестирование, использование, изменение, удаление.

Всегда тестируйте канал после создания, чтобы убедиться в работоспособности доставки:

curl -X POST "https://api.vilna.io/v1/channels/{channel_id}/actions/test" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "event_type": "transaction_detected" }'

Тест отправляет пример TransactionAlertPayload с is_test_message: true.

• Тестируйте перед использованием. Отправляйте тестовый payload сразу после создания канала.
• Проверяйте подписи вебхуков. Всегда валидируйте X-Webhook-Signature для подтверждения подлинности payload. Примеры кода см. в Аутентификации.
• Обрабатывайте дубликаты. Используйте X-Webhook-Event-Id (или поле event_id в теле) для пропуска повторных доставок - он стабилен между повторными попытками.
• Отвечайте быстро. Вебхук-эндпоинты должны возвращать HTTP 2xx в течение 10 секунд. Обрабатывайте payload асинхронно.
• Используйте отдельные каналы для разных окружений (разработка, стейджинг, продакшн) и разных целей (критические оповещения и рутинные уведомления).