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

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

# 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 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

-- 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;