Webhook Event Processing

When to Use

Use when building webhook receivers for CRM events, campaign tracking, or third-party integrations.

Core Patterns

1. Idempotent Processing

// Always check for duplicate events
const existing = await supabase
  .from('events')
  .select('id')
  .eq('external_id', event.id)
  .single();

if (existing.data) {
  return { status: 'duplicate', skipped: true };
}

2. Payload Validation

• Verify webhook signature (HMAC)
• Validate required fields exist
• Normalize data types (dates, enums)
• Log raw payload for debugging

3. State Machine

event_received → validated → processed → stored → notified
                    ↓
                  invalid → logged → alerted

4. Error Handling

• Return 200 immediately (acknowledge receipt)
• Process asynchronously
• Retry failed processing with exponential backoff
• Dead letter queue for persistent failures

Best Practices

• Always respond 200 to webhooks (prevent retries)
• Store raw payloads before processing
• Use idempotency keys
• Monitor webhook latency and failure rates