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

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

## Обзор

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


```mermaid
graph LR
    subgraph "Обнаружение событий"
        E[Блокчейн событие]
    end
    
    subgraph "Типы каналов"
        W[Webhook канал]
        EM[Email канал]
    end
    
    subgraph "Доставка"
        API[Ваш API Endpoint]
        INBOX[Email почта]
    end
    
    E --> W --> API
    E --> EM --> INBOX
```

## Типы каналов

### Webhook каналы

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

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

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


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

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


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


```bash
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-символа"
}'
```

**Ответ:**


```json
{
  "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](/apis/security#%D0%B1%D0%B5%D0%B7%D0%BE%D0%BF%D0%B0%D1%81%D0%BD%D0%BE%D1%81%D1%82%D1%8C-webhook).

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


```json
{
  "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 канала


```bash
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": [
    "cfo@company.com",
    "treasury@company.com"
  ],
  "timezone": "Europe/Moscow"
}'
```

**Ответ:**


```json
{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "type": "email",
  "name": "Оповещения финансовой команды",
  "email_addresses": [
    "cfo@company.com",
    "treasury@company.com"
  ],
  "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.
```

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

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

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


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

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

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


```bash
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` | Мягко удален, не может получать уведомления |


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

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


```bash
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МБ


## Логи каналов

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


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

**Ответ:**


```json
{
  "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 каналов

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


### Для Email каналов

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


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

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


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

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

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


```
Критические события → 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 Справочник](/apis/spec) - Полная документация API со всеми типами событий
- [Руководство по быстрому старту](/guides/quickstart) - Полный учебник по настройке