wulf-pulse/docs/WEBHOOKS_README.md

# Webhook Integration - Quick Start

## What's Been Implemented

✅ **Webhook Infrastructure**
- Webhook receiver endpoint: `/api/webhooks/autotask`
- Database tables for tracking webhook events
- Webhook processing service with automatic entity upsert
- Monitoring APIs for logs and statistics

✅ **Supported Entities**
- Companies, Tickets, Tasks, Projects, Time Entries, Contacts, Contracts, Configuration Items

✅ **Features**
- Real-time entity updates from Autotask
- Automatic data mapping and upsert to PostgreSQL
- Event logging and error tracking
- Duplicate event prevention
- Performance monitoring

## Quick Setup

### 1. Run Database Migration

```bash
docker exec pulse-postgres psql -U pulse_user -d pulse_autotask -f /app/migrations/004_webhook_support.sql
```

### 2. Configure Webhooks in Autotask

For each entity (Companies, Tickets, Tasks, etc.):

1. Go to Autotask → Admin → Webhooks
2. Create new webhook:
   - **URL:** `https://your-domain.com/api/webhooks/autotask`
   - **Entity:** Select entity type
   - **Events:** Create, Update
   - **Include Entity Data:** ✅ Enabled
3. Save and note the webhook ID

### 3. Test the Endpoint

```bash
# Health check
curl https://your-domain.com/api/webhooks/autotask

# View recent webhooks
curl https://your-domain.com/api/webhooks/logs?limit=10

# View statistics
curl https://your-domain.com/api/webhooks/stats?hours=24
```

## Recommended Sync Strategy

**Webhooks (Real-Time)** + **Daily Incremental Sync** + **Weekly Full Sync**

This combination ensures:
- ✅ Near-instant updates via webhooks
- ✅ Backup sync catches missed events
- ✅ Weekly refresh ensures data integrity

## Files Created

```
/lib/types/webhook.ts                    - TypeScript types
/lib/services/webhook-service.ts         - Webhook processing logic
/app/api/webhooks/autotask/route.ts      - Webhook receiver endpoint
/app/api/webhooks/logs/route.ts          - Logs API
/app/api/webhooks/stats/route.ts         - Statistics API
/migrations/004_webhook_support.sql      - Database schema
/docs/WEBHOOK_SETUP.md                   - Complete setup guide
```

## Next Steps

1. **Deploy the changes** - Rebuild and restart the application
2. **Run migration** - Create webhook tables in database
3. **Configure Autotask** - Set up webhooks for desired entities
4. **Monitor** - Check logs and statistics to verify webhooks are working

## Full Documentation

See [WEBHOOK_SETUP.md](./WEBHOOK_SETUP.md) for complete setup instructions, troubleshooting, and best practices.

## Architecture

```
Autotask → Webhook Event
    ↓
/api/webhooks/autotask (Receiver)
    ↓
WebhookService.processWebhook()
    ↓
1. Log event to webhook_logs
2. Validate entity type is active
3. Map Autotask data to PostgreSQL schema
4. Upsert to appropriate table
5. Update log status (processed/failed)
    ↓
Real-time data in PostgreSQL ✅
```

## Monitoring Queries

```sql
-- Recent webhooks
SELECT event_id, entity_type, entity_id, status, processing_time_ms
FROM webhook_logs
ORDER BY received_at DESC
LIMIT 20;

-- Failed webhooks
SELECT event_id, entity_type, error_message
FROM webhook_logs
WHERE status = 'failed'
ORDER BY received_at DESC;

-- Statistics by entity
SELECT entity_type, COUNT(*) as total,
       COUNT(*) FILTER (WHERE status = 'processed') as processed,
       COUNT(*) FILTER (WHERE status = 'failed') as failed,
       AVG(processing_time_ms) as avg_ms
FROM webhook_logs
WHERE received_at >= NOW() - INTERVAL '24 hours'
GROUP BY entity_type;
```