Webhook System

SkunkCRM provides a powerful webhook system for integrating with external services like n8n, Zapier, Make.com, and custom applications.

Overview

The webhook system supports two main patterns:

1. Outgoing Webhooks (Event Subscriptions) - SkunkCRM sends data TO external systems
2. Incoming Webhooks (Data Receivers) - External systems send data TO SkunkCRM

🚀 Outgoing Webhooks (Event Subscriptions)

Send CRM events to external systems when things happen in SkunkCRM.

Quick Setup

1. Go to SkunkCRM → Webhooks in your WordPress admin
2. Click "Add Webhook"
3. Configure:
   • Name: "n8n Lead Processing"
   • URL: Your webhook URL from n8n/Zapier/etc
   • Events: Select which CRM events to send
   • Authentication: Configure if needed

Available Events

Contact Events

• contact_created - New contact added
• contact_updated - Contact information changed
• contact_status_changed - Contact status changed (lead → customer)

Deal Events

• deal_created - New deal created
• deal_stage_changed - Deal moved between pipeline stages
• deal_won - Deal marked as won
• deal_lost - Deal marked as lost

Activity Events

• email_sent - Email sent from CRM
• email_opened - Email opened by recipient
• email_clicked - Link clicked in email

Automation Events

• automation_triggered - Automation workflow started
• automation_completed - Automation workflow finished

Task Events

• task_created - New task created
• task_completed - Task marked complete

Webhook Payload Format

All outgoing webhooks send JSON in this format:

{
  "event": "contact_created",
  "timestamp": "2025-01-09 14:30:00",
  "data": {
    "contact": {
      "id": 123,
      "name": "John Doe",
      "email": "john@example.com",
      "company": "Acme Corp",
      "status": "lead",
      "created_at": "2025-01-09 14:30:00"
    },
    "source": "api"
  },
  "context": {
    "request_source": "api",
    "user_id": 1
  },
  "source": {
    "system": "SkunkCRM",
    "version": "1.0",
    "url": "https://yoursite.com"
  }
}

Authentication Options

No Authentication

No additional headers required.

Bearer Token

Header: Authorization: Bearer your-secret-token

API Key Header

Header: X-API-Key: your-api-key

Basic Authentication

Header: Authorization: Basic base64(username:password)

📥 Incoming Webhooks (Data Receivers)

Receive data from external systems and automatically create/update contacts, deals, etc.

Quick Setup

1. Generate Token: Create a secure random token (e.g., abc123def456)
2. Use Endpoint: Send POST requests to:

   POST https://yoursite.com/wp-json/skunkcrm/v1/webhook/{your-token}
   

Example: Contact Data

curl -X POST "https://yoursite.com/wp-json/skunkcrm/v1/webhook/abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": {
      "name": "Jane Smith",
      "email": "jane@example.com", 
      "company": "Tech Corp",
      "phone": "+1-555-0123",
      "status": "lead",
      "source": "website_form"
    }
  }'

🛠️ REST API Reference

Webhook Management

# List all webhooks
GET /wp-json/skunkcrm/v1/webhooks

# Create webhook
POST /wp-json/skunkcrm/v1/webhooks
{
  "name": "n8n Integration",
  "url": "https://your-webhook-url.com",
  "events": ["contact_created", "deal_won"],
  "auth_type": "bearer",
  "auth_token": "your-secret-token"
}

# Get available events
GET /wp-json/skunkcrm/v1/webhooks/events

# Test webhook
POST /wp-json/skunkcrm/v1/webhooks/123/test

🔒 Security Best Practices

1. Use HTTPS: Always use HTTPS URLs for webhook endpoints
2. Strong Tokens: Use cryptographically secure random tokens
3. Rate Limiting: Implement appropriate rate limiting
4. Logging: Monitor webhook delivery for security issues

🐛 Troubleshooting

Common Issues

Webhook not firing:

• Verify webhook is active
• Check selected events match actual CRM events
• Review WordPress error logs

Authentication failing:

• Double-check token/credentials
• Verify header format matches expected format
• Test with curl first

Payload format issues:

• Use built-in webhook test feature
• Validate JSON syntax
• Check required field mappings