133 lines
3.9 KiB
Markdown
133 lines
3.9 KiB
Markdown
# 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!
|