Secure webhook controller for AWS SNS email events.

Handles incoming webhook notifications from AWS Simple Notification Service (SNS) for email events like bounces, complaints, deliveries, opens, and clicks.

Security Features

• SNS Signature Verification: Validates authentic AWS requests
• IP Whitelist: Restricts access to AWS IP ranges
• Rate Limiting: Prevents abuse with configurable limits
• Replay Attack Protection: Timestamp verification (max 5 minutes)
• Request Size Limits: Prevents oversized payloads
• Automatic Subscription Confirmation: Handles SNS subscription setup

Supported Event Types

All 10 AWS SES email event types are supported:

• Send: Email accepted by AWS SES for sending
• Reject: Email rejected before sending (virus, content policy violation)
• Bounce: Hard and soft bounces with detailed reasons
• Complaint: Spam complaints and feedback loops
• Delivery: Successful delivery confirmations
• Open: Email open detection (AWS SES tracking pixel)
• Click: Link click tracking in emails
• Rendering Failure: Email template rendering errors
• Delivery Delay: Temporary delivery delays
• Subscription: Subscription preference updates or unsubscribes

Configuration

Set these environment variables for security:

# Enable/disable specific security features
PHOENIX_KIT_WEBHOOK_VERIFY_SNS_SIGNATURE=true
PHOENIX_KIT_WEBHOOK_CHECK_AWS_IP=true
PHOENIX_KIT_WEBHOOK_RATE_LIMIT_ENABLED=true
PHOENIX_KIT_WEBHOOK_MAX_AGE_SECONDS=300

Usage

Add to your router:

# Public webhook endpoint (no authentication)
post "{prefix}/webhooks/email", PhoenixKitWeb.Controllers.EmailWebhookController, :handle

# Note: {prefix} is your configured PhoenixKit URL prefix (default: /phoenix_kit)

AWS SNS Setup

1. Create SNS topic for SES events
2. Subscribe this endpoint to the topic
3. Configure SES to publish events to the topic
4. The controller will automatically confirm subscriptions

Example Webhook Payload

%{
  "Type" => "Notification",
  "Message" => Jason.encode!(%{
    "eventType" => "bounce",
    "mail" => %{"messageId" => "abc123"},
    "bounce" => %{
      "bounceType" => "Permanent", 
      "bouncedRecipients" => [%{"emailAddress" => "user@example.com"}]
    }
  })
}