placebo.mk/STRAPI_WEBHOOKS_SETUP.md

# Strapi Webhooks Configuration Guide

## Overview
This guide explains how to configure Strapi webhooks for automatic synchronization with the backend API. When articles or live blogs are published/updated/deleted in Strapi, webhooks will automatically trigger synchronization with the backend.

## Webhook Endpoints

The backend provides three webhook endpoints:

1. **Article-specific webhook**: `POST /api/v1/webhooks/strapi/article`
2. **Live Blog-specific webhook**: `POST /api/v1/webhooks/strapi/live-blog`
3. **Generic webhook**: `POST /api/v1/webhooks/strapi` (handles both)

All endpoints accept the following JSON format:
```json
{
  "event": "entry.publish",  // or "entry.update", "entry.delete", "entry.unpublish"
  "model": "article",        // or "live-blog"
  "entry": {
    "documentId": "unique-strapi-id"
  }
}
```

## Configuration Steps

### Step 1: Access Strapi Admin Panel
1. Open your browser and go to: `http://localhost:1337/admin`
2. Log in with your admin credentials

### Step 2: Configure Webhooks
1. In the left sidebar, click on **Settings** (gear icon)
2. Click on **Webhooks** under the "GLOBAL SETTINGS" section
3. Click the **"Add new webhook"** button

### Step 3: Configure Article Webhook
**Basic Settings:**
- **Name**: `Backend Article Sync`
- **URL**: `http://localhost:3000/api/v1/webhooks/strapi/article`
  - For Docker internal communication: `http://backend:3000/api/v1/webhooks/strapi/article`
- **Headers**: Add if needed (usually not required)

**Trigger Events:**
Select the following events for the "Article" content type:
- [x] **Create entry** (`entry.create`)
- [x] **Update entry** (`entry.update`)
- [x] **Delete entry** (`entry.delete`)
- [x] **Publish entry** (`entry.publish`)
- [x] **Unpublish entry** (`entry.unpublish`)

**Save the webhook.**

### Step 4: Configure Live Blog Webhook (Optional)
Repeat Step 3 for live blogs:
- **Name**: `Backend Live Blog Sync`
- **URL**: `http://localhost:3000/api/v1/webhooks/strapi/live-blog`
- Select events for the "Live Blog" content type

### Alternative: Single Generic Webhook
You can use a single webhook for all content types:
- **Name**: `Backend Generic Sync`
- **URL**: `http://localhost:3000/api/v1/webhooks/strapi`
- Select events for ALL relevant content types (Article, Live Blog)

## Testing Webhooks

### Manual Test
You can manually trigger a webhook to test the configuration:

```bash
# Test article webhook
curl -X POST http://localhost:3000/api/v1/webhooks/strapi/article \
  -H "Content-Type: application/json" \
  -d '{
    "event": "entry.publish",
    "model": "article",
    "entry": {
      "documentId": "your-article-id"
    }
  }'

# Test generic webhook
curl -X POST http://localhost:3000/api/v1/webhooks/strapi \
  -H "Content-Type: application/json" \
  -d '{
    "event": "entry.publish",
    "model": "article",
    "entry": {
      "documentId": "your-article-id"
    }
  }'
```

### Test from Strapi
1. In Strapi admin, edit any article
2. Click "Save" or "Publish"
3. Check backend logs for webhook receipt:
   ```bash
   docker logs placebo-backend-dev --tail 20 | grep -i "webhook\|strapi"
   ```

## Manual Sync (Fallback)
If webhooks fail or for initial sync, use manual sync endpoints:

```bash
# Get authentication token first
curl -X POST http://localhost:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"your-username","password":"your-password"}'

# Sync all articles (requires auth)
curl -X POST http://localhost:3000/api/v1/webhooks/strapi/sync/all \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

# Sync all live blogs
curl -X POST http://localhost:3000/api/v1/webhooks/strapi/sync/live-blogs \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

# Sync everything
curl -X POST http://localhost:3000/api/v1/webhooks/strapi/sync/everything \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"
```

## Troubleshooting

### Common Issues

1. **Webhook not received by backend**
   - Check backend logs: `docker logs placebo-backend-dev --tail 50`
   - Verify CORS is configured (should allow `http://localhost:1337`)
   - Test webhook manually with curl

2. **401 Unauthorized error**
   - Webhook endpoints are now public (no auth required)
   - If getting 401, check that `@Public()` decorator is on webhook methods

3. **Webhook received but sync fails**
   - Check Strapi API token in backend `.env.docker`
   - Verify Strapi is accessible from backend container
   - Check backend logs for specific error messages

4. **Article not appearing in frontend**
   - Verify article is synced to backend: `curl http://localhost:3000/api/v1/articles`
   - Check frontend browser console for errors
   - Hard refresh frontend (Ctrl+F5)

### Log Monitoring
```bash
# Monitor backend logs for webhooks
docker logs -f placebo-backend-dev | grep -i "webhook\|strapi"

# Monitor Strapi logs
docker logs -f placebo-cms-dev

# Check if articles are in backend
curl -s "http://localhost:3000/api/v1/articles?status=published" | jq '.total'
```

## Docker Network Considerations

### Internal Docker Communication
- Within Docker network: Use `http://backend:3000` and `http://cms:1337`
- From host machine: Use `http://localhost:3000` and `http://localhost:1337`

### Webhook URL Examples
- **From Strapi container to Backend**: `http://backend:3000/api/v1/webhooks/strapi`
- **From Host to Backend**: `http://localhost:3000/api/v1/webhooks/strapi`
- **External/Production**: Use your domain: `https://api.yourdomain.com/api/v1/webhooks/strapi`

## Security Considerations

1. **Webhook endpoints are public** - ensure your backend is not exposed to the public internet in production
2. **Consider adding webhook signature verification** for production
3. **Use HTTPS in production** for all webhook calls
4. **Monitor webhook logs** for suspicious activity

## Verification Checklist

- [ ] Webhooks configured in Strapi admin
- [ ] Test webhook manually works
- [ ] Article publish in Strapi triggers sync
- [ ] Synced articles appear in backend API
- [ ] Frontend displays synced articles
- [ ] All event types tested (publish, update, delete)

## Support
If issues persist:
1. Check all service logs
2. Verify network connectivity between containers
3. Test each component independently
4. Review error messages in logs