Search documentation of phoenix_kit

# PhoenixKitWeb.Controllers.EmailWebhookController (phoenix_kit v1.6.19)

View Source

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"}]
        }
      })
    }

# Summary

## Functions

handle(conn, params)

Main webhook handler for AWS SNS notifications.

# Functions

# handle(conn, params)

Main webhook handler for AWS SNS notifications.

Processes all incoming webhook requests with full security validation.