Notification Channels
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Name: Vilna API
Author: Vilna

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.

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

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:

{
  "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.

Webhook Payload Format

{
  "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

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": [
    "[email protected]",
    "[email protected]"
  ],
  "timezone": "America/New_York"
}'

Response:

{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "type": "email",
  "name": "Finance Team Alerts",
  "email_addresses": [
    "[email protected]",
    "[email protected]"
  ],
  "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:

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

Updating a Channel

Modify channel settings:

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:

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:

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

Response:

{
  "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

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

For Email Channels

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

General Guidelines

Create separate channels for different purposes:
- Production vs staging environments
- Critical alerts vs regular notifications
- Different teams or departments
Use descriptive names to identify channels easily
Test channels before connecting to production subscriptions
Monitor channel health through logs and metrics
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 - Complete API documentation with all event types
Quick Start Guide - Complete setup tutorial

Notification ChannelsCopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from Claude

Overview

Channel Types

Webhook Channels

Creating a Webhook Channel

Webhook Security

Webhook Payload Format

Email Channels

Creating an Email Channel

Email Format Example

Channel Management

Listing Channels

Updating a Channel

Channel Status

Testing Channels

Delivery and Reliability

Webhook Delivery

Email Delivery

Channel Logs

Best Practices

For Webhook Channels

For Email Channels

General Guidelines

Common Patterns

Multi-Channel Setup

Failover Configuration

Environment Separation

Troubleshooting

Webhook Issues

Email Issues

Next Steps

Was this helpful?

Notification Channels
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude