Connect External Services

Incoming webhooks allow external systems to send data directly to your SkunkCRM. This is perfect for connecting contact forms, payment processors, and other external services.

Quick Setup

1. Generate a Webhook Token

1. Go to SkunkCRM → Webhooks in your WordPress admin
2. In the Incoming Webhook Tokens section, click "Create Token"
3. Enter a descriptive name (e.g., "Contact Form Integration")
4. Click "Create Token" to generate
5. Copy the complete webhook URL provided - you'll use this in external systems

2. Get Your Webhook URL

Your webhook URL will be automatically generated and displayed after creating a token:

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

The complete URL with token will be shown in the SkunkCRM interface - no need to manually construct it.

Supported Data Formats

Contact Data

The most common use case - creating new contacts from form submissions:

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",
      "notes": "Interested in premium plan"
    }
  }'

Form Submissions

For generic form data that should be converted to contacts:

curl -X POST "https://yoursite.com/wp-json/skunkcrm/v1/webhook/abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "form_submission": {
      "name": "John Doe",
      "email": "john@example.com",
      "company": "Acme Inc",
      "message": "Interested in your services",
      "phone": "+1-555-0199",
      "form_source": "contact_page"
    }
  }'

Lead Data

Specifically for lead generation:

curl -X POST "https://yoursite.com/wp-json/skunkcrm/v1/webhook/abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "lead": {
      "name": "Sarah Johnson",
      "email": "sarah@startup.com",
      "company": "Cool Startup",
      "source": "linkedin_ad",
      "notes": "Downloaded whitepaper"
    }
  }'

Action-Based Format (Recommended)

The modern format that gives you more control:

curl -X POST "https://yoursite.com/wp-json/skunkcrm/v1/webhook/abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create_contact",
    "data": {
      "name": "Alex Chen",
      "email": "alex@example.com",
      "company": "Example Corp",
      "status": "prospect",
      "custom_fields": {
        "utm_source": "google",
        "utm_campaign": "summer2025"
      }
    }
  }'

Response Format

Successful webhook processing returns:

{
  "success": true,
  "message": "Webhook received and processed",
  "token": "abc123",
  "result": {
    "action": "created",
    "contact_id": 456,
    "message": "New contact created from webhook"
  },
  "processing_successful": true
}

Common Integration Examples

Gravity Forms (WordPress)

1. Install a webhook add-on for Gravity Forms
2. Configure the webhook URL: https://yoursite.com/wp-json/skunkcrm/v1/webhook/{token}
3. Set the format to JSON
4. Map form fields to contact fields

Stripe Payments

1. In your Stripe dashboard, go to Webhooks
2. Add endpoint: https://yoursite.com/wp-json/skunkcrm/v1/webhook/{token}
3. Select events: customer.created, payment_intent.succeeded
4. SkunkCRM will automatically create contacts from customer data

External Contact Forms

For any external form system that supports webhooks:

1. Configure the webhook URL in the form system
2. Use the form_submission format shown above
3. Map your form fields to SkunkCRM contact fields

Smart Field Detection

SkunkCRM automatically detects common field patterns:

• Email: Any field containing a valid email address
• Name: Fields named name, full_name, first_name + last_name
• Phone: Fields containing phone number patterns
• Company: Fields named company, organization, business

This means even if external systems use different field names, SkunkCRM can often figure out what the data represents.

Security & Best Practices

Token Security

• Keep tokens private - never expose them in frontend code
• Use HTTPS - always use secure connections
• Rotate tokens - regularly generate new tokens for security

Rate Limiting

• Each token has built-in rate limiting
• Contact support if you need higher limits for legitimate use cases

Data Validation

• SkunkCRM validates all incoming data
• Invalid data is logged but won't crash the system
• Check webhook logs in WordPress admin for debugging

Troubleshooting

Webhook Not Working?

1. Check the token - Make sure you're using the correct token
2. Verify the URL - Ensure you're posting to the right endpoint
3. Check logs - Go to SkunkCRM → Webhooks and click "View Logs" on your webhook to see delivery history
4. Test with curl - Use the examples above to test manually

Contact Not Created?

1. Check required fields - At minimum, provide a name or email
2. Verify data format - Make sure you're sending valid JSON
3. Review field mapping - Check that your field names are recognized

Authentication Errors?

1. Token format - Don't include extra characters or spaces
2. HTTPS required - Some servers require secure connections
3. Check permissions - Ensure SkunkCRM has proper WordPress permissions

Next Steps

• Test your integration - Use the curl examples to verify everything works
• Set up monitoring - Check the webhook logs regularly
• Configure data mapping - Customize how external data maps to SkunkCRM fields

::rest-api-banner::

Need help with a specific integration? Check our WordPress Forms guide or Payment Processors guide for detailed setup instructions.