# Brevo Webhook Setup Guide

This guide explains how to register your Brevo webhook endpoint to receive email delivery events.

## Webhook Endpoint

Your webhook endpoint is available at:
```
https://your-domain.com/api/brevo-webhook
```

Replace `your-domain.com` with your actual CoinKrazy domain.

## Supported Events

The webhook handler processes the following Brevo events:

- **bounce** - Email bounced (permanent or temporary)
- **complaint** - Email marked as spam/complaint
- **unsubscribe** - User unsubscribed from emails
- **click** - User clicked a link in the email
- **open** - User opened the email
- **delivered** - Email successfully delivered
- **sent** - Email sent to Brevo

## Setup Instructions

### Step 1: Log in to Brevo Dashboard

1. Go to https://app.brevo.com
2. Sign in with your credentials

### Step 2: Navigate to Webhooks

1. Click on **Settings** in the left sidebar
2. Select **Webhooks** from the menu
3. Click **Create a webhook**

### Step 3: Configure Webhook

1. **Webhook URL**: Enter your endpoint URL
   ```
   https://your-domain.com/api/brevo-webhook
   ```

2. **Events**: Select all events you want to track:
   - ✓ Bounce
   - ✓ Complaint
   - ✓ Unsubscribe
   - ✓ Click
   - ✓ Open
   - ✓ Delivered
   - ✓ Sent

3. **Description**: Add a description (e.g., "CoinKrazy Email Tracking")

4. Click **Create**

### Step 4: Verify Webhook

After creating the webhook, Brevo will send a test event. Check your server logs to confirm receipt:

```
[Brevo Webhook] Received 1 event(s)
[Brevo Webhook] Email delivered to test@example.com
```

## Event Processing

### Bounce Events

When an email bounces:
- **Permanent bounces** are logged and the email is marked as invalid
- **Temporary bounces** are logged for monitoring

### Complaint Events

When a user marks an email as spam:
- The event is logged for compliance
- The user's email is marked as complained

### Unsubscribe Events

When a user unsubscribes:
- The event is logged
- The user's subscription status is updated

### Click and Open Events

These events are logged for campaign analytics:
- Click events track link engagement
- Open events track email opens
- Analytics are updated in real-time

## Testing

To test your webhook setup:

1. Create a test email campaign in the Email Campaign Manager
2. Send it to a test email address
3. Open the email and click links
4. Check the Brevo dashboard for event tracking
5. Verify events appear in your server logs

## Troubleshooting

### Webhook Not Receiving Events

1. Verify the webhook URL is correct and publicly accessible
2. Check that your firewall allows incoming requests from Brevo
3. Verify the webhook is enabled in Brevo dashboard
4. Check server logs for any errors

### Events Not Processing

1. Ensure the `/api/brevo-webhook` endpoint is properly configured
2. Check that the Brevo SMTP credentials are valid
3. Verify the database connection is working
4. Review server logs for processing errors

## Security Considerations

### IP Whitelisting

Brevo sends webhooks from these IP ranges:
- 185.107.232.0/22
- 185.107.236.0/22

Consider whitelisting these IPs for additional security.

### Signature Verification

For production, implement webhook signature verification:
1. Retrieve the webhook secret from Brevo dashboard
2. Verify the `X-Brevo-Signature` header on incoming requests
3. Compare the computed signature with the header value

See `server/api/brevo-webhook.ts` for implementation details.

## Email Templates

Your system includes 5 default email templates:

1. **Welcome Campaign** - New user onboarding
2. **Promotional Offer** - Special deals and bonuses
3. **Password Reset** - Transactional security
4. **Email Verification** - Account verification
5. **Re-engagement Campaign** - Win-back offers

All templates support variable substitution using `{{variableName}}` syntax.

## Campaign Analytics

After setting up webhooks, you can track:
- Email delivery rates
- Open rates
- Click rates
- Bounce rates
- Complaint rates
- Unsubscribe rates

Analytics are automatically updated as webhook events arrive.

## Support

For Brevo support, visit: https://help.brevo.com

For CoinKrazy support, contact your administrator.