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

Копировать

• Копировать для LLM

  Копировать страницу как Markdown для LLM
• Просмотреть как Markdown

  Открыть эту страницу как Markdown
• Открыть в ChatGPT

  Получить анализ от ChatGPT
• Открыть в Claude

  Получить инсайты от Claude
• Подключиться к Cursor

  Установить сервер MCP в Cursor
• Подключиться к VS Code

  Установить сервер MCP в VS Code

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

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

Типы каналов: сравнение

Вебхук-каналы

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

Создание вебхук-канала

curl -X POST "https://${VILNA_NAMESPACE}.vilna.app/notification_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"
      }
    }
  }'

Структура payload вебхука

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

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

• item — полный объект транзакции, включая события (переводы, комиссии) и записи активности с дельтами по адресам.
• references — справочные данные для токенов, блокчейнов и адресов, упомянутых в транзакции. Дополнительные API-вызовы для получения названий и символов не нужны.
• is_test_message — true, если payload был отправлен тестовым действием, false для реальных блокчейн-событий.

Заголовки безопасности вебхука

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

Верификация подписи

Для проверки подлинности вебхуков см. Верификация подписей вебхуков.

Telegram-каналы

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

Настройка

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

Создание Telegram-канала

curl -X POST "https://${VILNA_NAMESPACE}.vilna.app/notification_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 /notification_channels/{notification_channel_id}/logs. Ответ представляет собой пагинированный список, отсортированный по убыванию даты доставки.

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

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

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

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

Жизненный цикл канала

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

Тестирование канала

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

curl -X POST "https://${VILNA_NAMESPACE}.vilna.app/notification_channels/{notification_channel_id}/actions/test" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "message_type": "transaction_alert" }'

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

Лучшие практики

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

Дополнительные материалы

• Аутентификация — примеры кода для верификации подписей
• Ошибки и устранение неполадок — устранение проблем с доставкой вебхуков
• Platform API — полная документация эндпоинтов каналов уведомлений