Каналы уведомлений
Копировать для LLM
Копировать страницу как Markdown для LLM
Просмотреть как Markdown
Открыть эту страницу как Markdown
Открыть в ChatGPT
Получить анализ от ChatGPT
Открыть в Claude
Получить инсайты от Claude

Name: Vilna API
Author: Vilna

Каналы уведомлений определяют, куда и как вы получаете оповещения о блокчейн-событиях. Vilna поддерживает два типа каналов: Webhooks для программной интеграции и Email для удобочитаемых уведомлений.

Обзор

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

Типы каналов

Webhook каналы

Webhook каналы отправляют HTTP POST запросы на ваш сервер при возникновении событий. Это предпочтительный метод для автоматизированных систем и продакшн-интеграций.

Лучше всего подходит для:

Автоматизированной обработки платежей
Депозитных систем бирж
Дашбордов реального времени
Торговых ботов
Бэкенд интеграций

Возможности:

Доставка в реальном времени (< 1 секунды)
Данные в формате JSON
Верификация подписи HMAC
Автоматические повторные попытки
Логи доставки

Создание Webhook канала

curl -X POST https://api.vilna.io/v1/channels \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "type": "webhook",
  "name": "Production Webhook",
  "webhook_url": "https://your-app.com/api/webhook",
  "webhook_secret": "ваш-секретный-ключ-минимум-32-символа"
}'

Ответ:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "webhook",
  "name": "Production Webhook",
  "webhook_url": "https://your-app.com/api/webhook",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}

Безопасность Webhook

Все webhook запросы включают заголовки безопасности для верификации:

Заголовок	Описание
`X-Vilna-Signature`	HMAC-SHA256 подпись тела запроса
`X-Vilna-Timestamp`	Unix timestamp когда запрос был отправлен
`X-Vilna-Event-Id`	Уникальный идентификатор для идемпотентности

Подробная информация о верификации webhook, расчете подписи и примеры кода доступны в документации по безопасности API.

Формат полезной нагрузки Webhook

{
  "event_type": "transaction.confirmed",
  "event_id": "evt_01234567-89ab-cdef-0123-456789abcdef",
  "timestamp": "2024-01-15T10:35:00Z",
  "channel_id": "550e8400-e29b-41d4-a716-446655440000",
  "subscription_id": "660e8400-e29b-41d4-a716-446655440001",
  "data": {
    "transaction_gid": "eip155:1:0xabc123...",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f7B123",
    "amount": "100.50",
    "asset_gid": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "confirmations": 12,
    "block_number": 18750000
  }
}

Email каналы

Email каналы отправляют удобочитаемые уведомления на указанные адреса электронной почты. Идеально подходят для оповещений, отчетов и ручного контроля.

Лучше всего подходит для:

Мониторинга казначейских оповещений
Ежедневных/еженедельных отчетов
Уведомлений о соответствии требованиям
Процессов ручной проверки
Экстренных оповещений

Возможности:

Форматированные HTML письма
Несколько получателей
Пользовательские шаблоны
Поддержка вложений (отчеты)
Поддержка часовых поясов

Создание Email канала

curl -X POST https://api.vilna.io/v1/channels \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "type": "email",
  "name": "Оповещения финансовой команды",
  "email_addresses": [
    "[email protected]",
    "[email protected]"
  ],
  "timezone": "Europe/Moscow"
}'

Ответ:

{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "type": "email",
  "name": "Оповещения финансовой команды",
  "email_addresses": [
    "[email protected]",
    "[email protected]"
  ],
  "timezone": "Europe/Moscow",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}

Пример формата Email

Тема: [Vilna Alert] Получен крупный депозит - 1,000 USDC

Тело письма:

Оповещение о транзакции

Получен крупный депозит:

Сумма: 1,000 USDC
Адрес: 0x742d...B123 (Казначейский кошелек)
От: 0x456d...C456
Транзакция: 0xabc123...
Подтверждения: 12
Время: 15 янв. 2024 10:35 МСК

Посмотреть в панели управления: [Ссылка на панель управления]

Это автоматическое уведомление от Vilna.

Управление каналами

Список каналов

Получить все каналы для вашего аккаунта:

curl https://api.vilna.io/v1/channels \
-H "Authorization: Bearer YOUR_API_KEY"

Обновление канала

Изменить настройки канала:

curl -X PATCH https://api.vilna.io/v1/channels/{channel_id} \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "name": "Обновленное название канала",
  "status": "paused"
}'

Статус канала

Каналы могут иметь следующие статусы:

Статус	Описание
`active`	Канал работает и будет получать уведомления
`paused`	Временно отключен, может быть активирован заново
`failed`	Слишком много ошибок доставки, требует внимания
`deleted`	Мягко удален, не может получать уведомления

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

Отправьте тестовое уведомление для проверки работы канала:

curl -X POST https://api.vilna.io/v1/channels/{channel_id}/test \
-H "Authorization: Bearer YOUR_API_KEY"

Это отправит тестовое событие с примером данных на ваш канал.

Доставка и надежность

Доставка Webhook

Политика повторных попыток:

Начальная попытка
Повтор через 10 секунд
Повтор через 1 минуту
Повтор через 5 минут
Повтор через 30 минут
Повтор через 2 часа

После 5 неудачных попыток канал помечается как failed.

Требования:

Должен вернуть HTTP 2xx в течение 10 секунд
Должен принимать application/json
Должен быть публично доступен (без IP ограничений для Vilna)

Доставка Email

Гарантии доставки:

Письма ставятся в очередь и повторяются при временных сбоях
Отслеживаются квитанции о доставке
Обработка отказов с автоматическим повтором
SPF/DKIM аутентификация для лучшей доставляемости

Ограничения:

Максимум 10 получателей на канал
Максимум 1000 писем в день на канал
Вложения ограничены 10МБ

Логи каналов

Просмотр истории доставки для устранения неполадок:

curl https://api.vilna.io/v1/channels/{channel_id}/logs \
-H "Authorization: Bearer YOUR_API_KEY"

Ответ:

{
  "items": [
    {
      "id": "log_01234567",
      "event_id": "evt_01234567",
      "status": "delivered",
      "attempts": 1,
      "delivered_at": "2024-01-15T10:35:00Z",
      "response_code": 200,
      "response_time_ms": 145
    },
    {
      "id": "log_01234568",
      "event_id": "evt_01234568",
      "status": "failed",
      "attempts": 5,
      "last_attempt_at": "2024-01-15T12:35:00Z",
      "error": "Connection timeout",
      "next_retry_at": null
    }
  ],
  "meta": {
    "total": 156,
    "page": 1,
    "limit": 20
  }
}

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

Для Webhook каналов

Реализуйте проверку подписи - Всегда проверяйте HMAC подпись
Отвечайте быстро - Возвращайте 200 OK немедленно, обрабатывайте асинхронно
Обрабатывайте дубликаты - Используйте event_id для идемпотентности
Мониторьте ваш endpoint - Настройте оповещения о сбоях
Используйте HTTPS - Всегда используйте зашифрованные соединения
Реализуйте circuit breakers - Предотвращайте каскадные сбои

Для Email каналов

Используйте групповые адреса - Вместо индивидуальных email
Настройте фильтры - Организуйте уведомления в вашем почтовом ящике
Настройте SPF записи - Авторизуйте Vilna отправлять от вашего имени
Мониторьте доставку - Проверяйте логи на наличие отказов
Используйте подходящий объем - Не перегружайте почтовые ящики

Общие рекомендации

Создавайте отдельные каналы для разных целей:
- Продакшн vs staging окружения
- Критические оповещения vs обычные уведомления
- Разные команды или отделы
Используйте описательные названия для легкой идентификации каналов
Тестируйте каналы перед подключением к продакшн подпискам
Мониторьте состояние каналов через логи и метрики
Имейте резервные каналы для критичных уведомлений

Распространенные паттерны

Настройка мульти-каналов

Создайте несколько каналов для разных уровней важности:

Критические события → Webhook + Email → Немедленное действие
Обычные события   → Только Webhook   → Автоматическая обработка
Отчеты            → Только Email     → Ежедневный/еженедельный обзор

Конфигурация отказоустойчивости

Настройте основной и резервный каналы:

Основной: Production webhook endpoint
Резервный: Email команде операций

Оба канала получают одинаковые события, обеспечивая доставку даже при сбое основного.

Разделение окружений

Используйте разные каналы для каждого окружения:

Development  → https://dev.company.com/webhook
Staging      → https://staging.company.com/webhook  
Production   → https://api.company.com/webhook

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

Проблемы с Webhook

Не получаете webhooks:

Проверьте публичную доступность URL
Проверьте правила файрвола
Подтвердите активность подписки
Просмотрите логи канала на наличие ошибок

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

Убедитесь в использовании правильного секрета
Не изменяйте тело запроса перед проверкой
Проверьте проблемы с кодировкой

Получаете дубликаты:

Реализуйте идемпотентность с event_id
Проверьте, не истекает ли таймаут endpoint
Убедитесь в правильном возврате 200 OK

Проблемы с Email

Не получаете письма:

Проверьте папки спам/нежелательная почта
Убедитесь в правильности email адресов
Проверьте, не превышен ли дневной лимит
Просмотрите логи канала

Письма попадают в спам:

Добавьте Vilna в разрешенных отправителей
Настройте SPF записи
Проверьте фильтры содержимого email

Следующие шаги

API Справочник - Полная документация API со всеми типами событий
Руководство по быстрому старту - Полный учебник по настройке

Обзор

Типы каналов

Webhook каналы

Создание Webhook канала

Безопасность Webhook

Формат полезной нагрузки Webhook

Email каналы

Создание Email канала

Пример формата Email

Управление каналами

Список каналов

Обновление канала

Статус канала

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

Доставка и надежность

Доставка Webhook

Доставка Email

Логи каналов

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

Для Webhook каналов

Для Email каналов

Общие рекомендации

Распространенные паттерны

Настройка мульти-каналов

Конфигурация отказоустойчивости

Разделение окружений

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

Проблемы с Webhook

Проблемы с Email

Следующие шаги

Это было полезно?