🔒 AhaSend Webhook Handler (Secured)
This Cloudflare Worker handles AhaSend webhook notifications and incoming email routing with enterprise-grade security.
✅ Database Connected: All webhook events and emails are stored in D1 Database!
🔐 Security Enabled: HMAC Signature Verification & Replay Attack Protection
🟢 Database Ready - Tables Created Successfully
🔐 Security Features:
- 🔒 HMAC Signature Verification - Standard Webhooks specification compliance
- ⏰ Timestamp Validation - Prevents replay attacks (5-minute tolerance)
- 🛡️ Required Headers Check - webhook-signature, webhook-timestamp, webhook-id
- 🔍 Timing-Safe Comparison - Prevents timing attack vectors
- 📋 Security Audit Trail - All verification attempts logged in database
- 🔑 Dual Secret Support - Separate secrets for webhooks and email routing
Available Endpoints:
POST /webhook
🔒 SECURED with WEBHOOK_SECRET: Receives AhaSend webhook notifications with signature verification
Supported events: message.*, suppression.created, domain.dns_error
Required Headers:
webhook-signature - HMAC-SHA256 signaturewebhook-timestamp - Unix timestampwebhook-id - Unique event identifier
POST /incoming-email
🔒 SECURED with ROUTE_SECRET: Handles incoming email routing and processing with signature verification
Uses separate route secret for email routing security
Required Headers:
webhook-signature - HMAC-SHA256 signature (using ROUTE_SECRET)webhook-timestamp - Unix timestampwebhook-id - Unique event identifier
GET /attachments/{id}
📎 NEW: Download email attachments stored in R2 bucket
Secure direct access to attachment files with proper content headers
GET /stats
Returns comprehensive analytics and statistics from D1 database
Includes security metrics, signature validation stats, and R2 storage analytics
GET /health
Health check endpoint
Supported AhaSend Events:
- message.reception - Email received and queued for delivery
- message.delivered - Email successfully delivered
- message.transient_error - Email has transient error, will retry
- message.failed - Email delivery failed permanently
- message.bounced - Email bounced
- message.opened - Email opened by recipient
- message.suppressed - Email suppressed
- suppression.created - New suppression created
- domain.dns_error - DNS configuration error detected
Database Storage:
All webhook events and incoming emails are automatically stored with:
- 📊 Event analytics and statistics
- 🔍 Full audit trail with timestamps
- 💾 Raw payload preservation
- 📈 Daily processing metrics
- ⚠️ Error tracking and reporting
- 🌐 IP/User-Agent tracking
- 🔐 Signature validation status
- 🛡️ Security incident logging
📎 R2 Object Storage:
Email attachments are efficiently stored in Cloudflare R2 with:
- 🗄️ Optimized Storage: Large files stored in R2, metadata in D1
- 📋 Smart Organization: Attachments organized by email ID and timestamp
- 🔒 Secure Access: Direct download via
/attachments/{id} endpoint
- 📊 Upload Tracking: Success/failure status monitoring
- 🏷️ Rich Metadata: Original filename, content type, and email context preserved
- ⚡ High Performance: CDN-backed global delivery
- 💰 Cost Effective: Only pay for storage used, not database space
⚙️ Setup Instructions:
- Set Webhook Secret:
npx wrangler secret put WEBHOOK_SECRET
- Set Route Secret:
npx wrangler secret put ROUTE_SECRET
- Configure AhaSend Webhooks: URL:
https://your-worker-url.workers.dev/webhook
- Configure AhaSend Email Routing: URL:
https://your-worker-url.workers.dev/incoming-email
- Content Type:
application/json for both endpoints
- Security: Use respective secrets from AhaSend dashboard (webhook vs route)
View statistics and security metrics at: https://your-worker-url.workers.dev/stats
⚠️ Security Notice: This webhook handler requires proper HMAC signature verification.
Requests without valid signatures will be rejected with 401 status code. Different endpoints use different secrets:
- Webhooks: Use WEBHOOK_SECRET
- Email Routing: Use ROUTE_SECRET