# 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

```bash
# 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:

```bash
# 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)
```json
{
  "Type": "Notification",
  "Message": "{\"notificationType\":\"Bounce\",\"bounce\":{...}}"
}
```

### 3. Notification (Complaint)
```json
{
  "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!