sasa-maillist/SNS_DEBUG_GUIDE.md

SNS Webhook Debugging Guide

Current Status

✅ Detailed logging is now active! The API will log all incoming SNS requests with:

• Full headers (including SNS-specific headers)
• Request body content
• Parsed message structure
• Processing steps and results

How to View Logs in Real-Time

# Watch API logs as SNS sends notifications
sudo docker compose logs api -f

Testing with Real AWS SNS

Step 1: Trigger a Test from SNS Console

1. Go to AWS SNS Console → Your Topic
2. Click "Publish message"
3. Send a test notification

Step 2: Check the Logs

The logs will show you exactly what SNS sent:

============================================================
SNS Webhook Request Received
============================================================
Content-Type: text/plain; charset=UTF-8
User-Agent: Amazon Simple Notification Service Agent
X-Amz-SNS-Message-Type: Notification
X-Amz-SNS-Topic-Arn: arn:aws:sns:...

Message Type: Notification
Message Keys: ['Type', 'MessageId', 'TopicArn', 'Message', ...]

✓ Notification Received
  Message (first 200 chars): {"notificationType":"Bounce",...
  Notification Type: Bounce

✓ Processing Bounce
  Bounce Type: Permanent
  Recipients: ['bounce@example.com']
  ✓ Bounce processed successfully
============================================================

What the Logs Tell You

If you see this:

• "SNS webhook received body: b''" → SNS sent empty body (check SNS configuration)
• "Missing SigningCertURL" → Message missing required SNS fields
• "Invalid certificate URL" → Certificate URL not from amazonaws.com
• "Invalid signature" → Signature verification failed (message tampered or wrong cert)

Successful Flow:

1. Headers logged → Shows SNS user agent and message type
2. Body logged → Shows the raw JSON
3. Message parsed → Shows the Type field
4. Notification processed → Shows bounce/complaint details
5. Database updated → Confirmation of processing

Understanding Previous Errors

The error you saw earlier:

SNS webhook error: Expecting value: line 1 column 1 (char 0)

This means SNS was sending an empty body or the body was already consumed. Possible causes:

1. SNS subscription confirmation URL was opened in a browser (GET request, not POST)
2. Network issue causing body to be lost
3. SNS configuration issue

Testing Bounce Handling

Option 1: AWS SES Bounce Simulator

Send email to: bounce@simulator.amazonses.com

Option 2: Verify Database Updates

After a bounce is processed:

# Check bounce logs
sudo docker compose exec mysql mysql -u maillist -pmaillist maillist -e "SELECT * FROM bounce_logs ORDER BY created_at DESC LIMIT 5;"

# Check member bounce status
sudo docker compose exec mysql mysql -u maillist -pmaillist maillist -e "SELECT member_id, email, bounce_count, bounce_status, last_bounce_at FROM members WHERE bounce_count > 0;"

Common SNS Message Types

1. SubscriptionConfirmation

First message when you create the subscription. API auto-confirms by calling SubscribeURL.

2. Notification (Bounce)

{
  "Type": "Notification",
  "Message": "{\"notificationType\":\"Bounce\",\"bounce\":{...}}"
}

3. Notification (Complaint)

{
  "Type": "Notification",
  "Message": "{\"notificationType\":\"Complaint\",\"complaint\":{...}}"
}

Next Steps

1. Monitor logs while SNS sends: sudo docker compose logs api -f
2. Trigger a real bounce: Send to bounce@simulator.amazonses.com
3. Check the detailed logs to see exactly what SNS is sending
4. Verify database updates to confirm bounces are being recorded

If You Still See Errors

The enhanced logging will now show you:

• What headers SNS is sending
• What body content is arriving (or if it's empty)
• Where in the processing pipeline the error occurs
• Full stack traces for any exceptions

Copy the relevant log section and we can diagnose the exact issue!