# Notification Channels

Notification channels define where and how you receive alerts about blockchain events. Vilna supports two types of channels: Webhooks for programmatic integration and Email for human-readable notifications.

## Overview

Channels are the delivery mechanism for blockchain event notifications. Once you've set up monitoring for your addresses, channels determine where those notifications are sent.


```mermaid
graph LR
    subgraph "Event Detection"
        E[Blockchain Event]
    end
    
    subgraph "Channel Types"
        W[Webhook Channel]
        EM[Email Channel]
    end
    
    subgraph "Delivery"
        API[Your API Endpoint]
        INBOX[Email Inbox]
    end
    
    E --> W --> API
    E --> EM --> INBOX
```

## Channel Types

### Webhook Channels

Webhook channels send HTTP POST requests to your server when events occur. This is the preferred method for automated systems and production integrations.

**Best for:**

- Automated payment processing
- Exchange deposit systems
- Real-time dashboards
- Trading bots
- Backend integrations


**Features:**

- Real-time delivery (< 1 second)
- JSON formatted data
- HMAC signature verification
- Automatic retries
- Delivery logs


#### Creating a Webhook Channel


```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": "your-secret-key-min-32-chars"
}'
```

**Response:**


```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 Security

All webhook requests include security headers for verification:

| Header | Description |
|  --- | --- |
| `X-Vilna-Signature` | HMAC-SHA256 signature of the request body |
| `X-Vilna-Timestamp` | Unix timestamp when the request was sent |
| `X-Vilna-Event-Id` | Unique identifier for idempotency |


For detailed information about webhook verification, signature calculation, and code examples, see the [API Security documentation](/apis/security#webhook-security).

#### Webhook Payload Format


```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 Channels

Email channels send human-readable notifications to specified email addresses. Perfect for alerts, reports, and manual oversight.

**Best for:**

- Treasury monitoring alerts
- Daily/weekly reports
- Compliance notifications
- Manual review processes
- Emergency alerts


**Features:**

- Formatted HTML emails
- Multiple recipients
- Custom templates
- Attachment support (reports)
- Timezone support


#### Creating an Email Channel


```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": "Finance Team Alerts",
  "email_addresses": [
    "cfo@company.com",
    "treasury@company.com"
  ],
  "timezone": "America/New_York"
}'
```

**Response:**


```json
{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "type": "email",
  "name": "Finance Team Alerts",
  "email_addresses": [
    "cfo@company.com",
    "treasury@company.com"
  ],
  "timezone": "America/New_York",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}
```

#### Email Format Example

**Subject:** `[Vilna Alert] Large Deposit Received - 1,000 USDC`

**Body:**


```
Transaction Alert

A large deposit has been received:

Amount: 1,000 USDC
Address: 0x742d...B123 (Treasury Wallet)
From: 0x456d...C456
Transaction: 0xabc123...
Confirmations: 12
Time: Jan 15, 2024 10:35 AM EST

View in Dashboard: [Dashboard Link]

This is an automated notification from Vilna.
```

## Channel Management

### Listing Channels

Get all channels for your account:


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

### Updating a Channel

Modify channel settings:


```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": "Updated Channel Name",
  "status": "paused"
}'
```

### Channel Status

Channels can have the following statuses:

| Status | Description |
|  --- | --- |
| `active` | Channel is operational and will receive notifications |
| `paused` | Temporarily disabled, can be reactivated |
| `failed` | Too many delivery failures, needs attention |
| `deleted` | Soft deleted, cannot receive notifications |


### Testing Channels

Send a test notification to verify your channel is working:


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

This sends a test event with sample data to your channel.

## Delivery and Reliability

### Webhook Delivery

**Retry Policy:**

- Initial attempt
- Retry after 10 seconds
- Retry after 1 minute
- Retry after 5 minutes
- Retry after 30 minutes
- Retry after 2 hours


After 5 failed attempts, the channel is marked as `failed`.

**Requirements:**

- Must return HTTP 2xx within 10 seconds
- Must accept `application/json`
- Must be publicly accessible (no IP restrictions for Vilna)


### Email Delivery

**Delivery Guarantees:**

- Emails are queued and retried on temporary failures
- Delivery receipts are tracked
- Bounce handling with automatic retry
- SPF/DKIM authentication for better deliverability


**Limitations:**

- Maximum 10 recipients per channel
- Maximum 1000 emails per day per channel
- Attachments limited to 10MB


## Channel Logs

View delivery history for troubleshooting:


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

**Response:**


```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
  }
}
```

## Best Practices

### For Webhook Channels

1. **Implement signature verification** - Always verify the HMAC signature
2. **Respond quickly** - Return 200 OK immediately, process async
3. **Handle duplicates** - Use event_id for idempotency
4. **Monitor your endpoint** - Set up alerting for failures
5. **Use HTTPS** - Always use encrypted connections
6. **Implement circuit breakers** - Prevent cascade failures


### For Email Channels

1. **Use group addresses** - Instead of individual emails
2. **Set up filters** - Organize notifications in your inbox
3. **Configure SPF records** - Authorize Vilna to send on your behalf
4. **Monitor delivery** - Check logs for bounces
5. **Use appropriate volume** - Don't overwhelm inboxes


### General Guidelines

1. **Create separate channels** for different purposes:
  - Production vs staging environments
  - Critical alerts vs regular notifications
  - Different teams or departments
2. **Use descriptive names** to identify channels easily
3. **Test channels** before connecting to production subscriptions
4. **Monitor channel health** through logs and metrics
5. **Have backup channels** for critical notifications


## Common Patterns

### Multi-Channel Setup

Create multiple channels for different severity levels:


```
Critical Events → Webhook + Email → Immediate action
Normal Events  → Webhook only    → Automated processing
Reports        → Email only      → Daily/weekly review
```

### Failover Configuration

Set up primary and backup channels:


```
Primary: Production webhook endpoint
Backup:  Email to ops team
```

Both channels receive the same events, ensuring delivery even if the primary fails.

### Environment Separation

Use different channels for each environment:


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

## Troubleshooting

### Webhook Issues

**Not receiving webhooks:**

- Verify URL is publicly accessible
- Check firewall rules
- Confirm subscription is active
- Review channel logs for errors


**Signature verification failing:**

- Ensure using correct secret
- Don't modify request body before verification
- Check for encoding issues


**Receiving duplicates:**

- Implement idempotency with event_id
- Check if endpoint is timing out
- Verify returning 200 OK properly


### Email Issues

**Not receiving emails:**

- Check spam/junk folders
- Verify email addresses are correct
- Check daily limit hasn't been exceeded
- Review channel logs


**Emails going to spam:**

- Add Vilna to allowed senders
- Configure SPF records
- Check email content filters


## Next Steps

- [API Reference](/apis/spec) - Complete API documentation with all event types
- [Quick Start Guide](/guides/quickstart) - Complete setup tutorial