Webhook Integration

Overview

CloudCusp Mailer provides comprehensive webhook integration capabilities for connecting your email marketing with external systems and applications. Use incoming webhooks to trigger automations from third-party services and outgoing webhooks to sync data to external platforms.

Webhook Basics

What are Webhooks?

Webhooks are automated HTTP POST requests that send real-time data from one application to another:

Key Characteristics:

Event-driven communication
Real-time data synchronization
No polling required
HTTP/REST-based
Secure payload delivery
Event history and logging

Use Cases:

CRM integration (Salesforce, HubSpot, Pipedrive)
Custom application synchronization
Lead scoring systems
Data warehouse updates
Third-party notification systems
Analytics platform integration

Incoming Webhooks

What are Incoming Webhooks?

Receive data from external systems and trigger CloudCusp Mailer actions:

Flow:

External System → HTTP POST → CloudCusp Webhook Endpoint
                                        ↓
                              Parse & Process Event
                                        ↓
                              Trigger Action/Automation

Create Incoming Webhook

Set up new incoming webhook endpoint:

Go to CloudCusp Mailer → Webhooks → Incoming
Click Create Webhook
Enter webhook name
Select trigger event type
Configure actions
Set security credentials
Generate unique URL
Save webhook

Webhook Creation Form:

Field	Description	Required
Name	Webhook identifier	Yes
Event Type	What triggers this webhook	Yes
Description	Internal notes	No
Status	Active/Inactive	Yes
API Key	Authentication token	Yes

Incoming Event Types

Supported webhook triggers:

Subscriber Events:

subscriber_added - New subscriber created
subscriber_updated - Subscriber data changed
subscriber_deleted - Subscriber removed
subscriber_status_changed - Status (subscribed/unsubscribed) changed
subscriber_tagged - Tag applied to subscriber
subscriber_untagged - Tag removed from subscriber

Email Events:

email_sent - Email delivered
email_opened - Email opened by subscriber
email_clicked - Link clicked in email
email_bounced - Email delivery failed
email_complained - Marked as spam

Campaign Events:

campaign_created - New campaign created
campaign_sent - Campaign sending started
campaign_completed - Campaign finished
campaign_failed - Campaign sending failed

Custom Events:

Create custom events for integration
Send from external systems
Trigger specific workflows

Webhook Endpoint URL

Auto-generated unique URL for receiving webhooks:

Format:

https://yoursiteurl.com/wp-json/ccsp-mailer/v1/webhooks/
{webhook_id}?token={unique_token}

Example:

https://example.com/wp-json/ccsp-mailer/v1/webhooks/
a1b2c3d4e5f6?token=abc123def456xyz789

URL Components:

Webhook ID: Unique identifier
Token: Security token
API version: v1
Include both in webhook configuration

Payload Structure

Data format for incoming webhook:

Subscriber Added Event:

json

{
  "event": "subscriber_added",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "subscriber_id": 123,
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "list_id": 1,
    "status": "subscribed",
    "source": "form_submission",
    "custom_fields": {
      "company": "Acme Corp",
      "phone": "+1234567890"
    }
  }
}

Email Opened Event:

json

{
  "event": "email_opened",
  "timestamp": "2024-01-15T11:45:00Z",
  "data": {
    "subscriber_id": 123,
    "subscriber_email": "john@example.com",
    "campaign_id": 456,
    "campaign_name": "January Newsletter",
    "device_type": "desktop",
    "email_client": "Gmail",
    "ip_address": "192.168.1.1",
    "user_agent": "Mozilla/5.0...",
    "open_count": 1
  }
}

Webhook Actions

Configure what happens when webhook received:

Available Actions:

1. Add Subscriber

Create new subscriber if not exists
Map incoming fields to subscriber fields
Add to specific lists
Apply tags automatically
Set custom fields

2. Update Subscriber

Update existing subscriber
Match by email address
Update multiple fields
Add/remove tags
Update custom fields

3. Add to List

Subscribe to specific list
Support double opt-in workflow
Update list membership
Trigger welcome email

4. Remove from List

Unsubscribe from list
Update status
Trigger exit automation

5. Apply Tag

Add tag to subscriber
Multiple tags supported
Segment management

6. Change Status

Update subscriber status
Subscribed, unsubscribed, pending
Bounce/complaint handling

7. Trigger Automation

Start automation workflow
Pass webhook data
Create automation run

8. Create CRM Record

Sync to external CRM
Map fields to CRM
Update existing records

9. Custom Action

Execute custom code
Call external API
Process data transformation

Field Mapping

Map incoming webhook data to subscriber fields:

Mapping Configuration:

Incoming Field → Subscriber Field
├─ contact_email → email (required)
├─ first_name → first_name
├─ last_name → last_name
├─ phone_number → phone
├─ company_name → custom_field.company
├─ subscription_source → subscription_source
└─ utm_source → custom_field.utm_source

Mapping Options:

Standard fields (email, name, phone)
Custom fields (JSON values)
Date transformation
Field concatenation
Conditional mapping

Security Configuration

Secure incoming webhook:

Authentication:

Unique Token: Auto-generated security token
Regenerate: Create new token if compromised
Request Signature: HMAC-SHA256 verification
IP Whitelist: Restrict sender IPs (optional)
API Key: Additional authentication layer

Security Headers:

Verify SSL certificate
Check HMAC signature
Validate API key
Log suspicious requests
Rate limiting enabled

Retry Logic

Handle webhook delivery failures:

Retry Configuration:

Initial delivery attempt
Retry after 5 minutes
Retry after 30 minutes
Retry after 2 hours
Maximum 3 retry attempts
Total delivery window: 2 hours

Status Tracking:

Successful delivery (200-299)
Failed delivery (logged)
Retry attempts recorded
Error messages stored
Manual retry option

Webhook Logs

View webhook activity and debugging:

Go to CloudCusp Mailer → Webhooks → Incoming
Click webhook name
View activity log

Log Information:

Event timestamp
Event type
Sender IP
Payload received
Processing status
Actions executed
Errors/warnings
Response sent

Log Actions:

View full payload
Retry webhook
Re-send data
Export logs
Clear logs

Outgoing Webhooks

What are Outgoing Webhooks?

Send CloudCusp Mailer events to external systems in real-time:

Flow:

CloudCusp Event Occurs
        ↓
Trigger Outgoing Webhook
        ↓
HTTP POST to External System
        ↓
External System Processes Data

Create Outgoing Webhook

Configure new outgoing webhook:

Go to CloudCusp Mailer → Webhooks → Outgoing
Click Create Webhook
Enter webhook name
Enter external API endpoint URL
Select trigger events
Configure payload
Set authentication
Test connection
Save webhook

Configuration Form:

Field	Description	Required
Name	Webhook identifier	Yes
Endpoint URL	External system API URL	Yes
Events	What triggers send	Yes
Auth Method	How to authenticate	No
API Key	For authentication	No
Custom Headers	Additional headers	No
Status	Active/Inactive	Yes

Outgoing Event Types

CloudCusp events sent to external systems:

Available Triggers:

subscriber_added
subscriber_updated
subscriber_deleted
subscriber_status_changed
email_sent
email_opened
email_clicked
email_bounced
campaign_completed

Webhook Payload Configuration

Customize data sent to external system:

Payload Builder:

json

{
  "event_type": "{event_type}",
  "timestamp": "{timestamp}",
  "subscriber": {
    "id": "{subscriber_id}",
    "email": "{subscriber_email}",
    "first_name": "{subscriber_first_name}",
    "custom_field": "{subscriber_custom_field_id}"
  },
  "campaign": {
    "id": "{campaign_id}",
    "name": "{campaign_name}"
  },
  "custom_data": {
    "your_field": "your_value"
  }
}

Available Variables:

{subscriber_id}
{subscriber_email}
{subscriber_first_name}
{subscriber_last_name}
{subscriber_phone}
{subscriber_lists}
{subscriber_tags}
{campaign_id}
{campaign_name}
{campaign_sent_date}
{event_type}
{timestamp}
{custom_field_*}

Authentication Methods

Secure outgoing webhooks:

1. No Authentication

Send without authentication
Use for public endpoints
Verify with IP whitelist

2. API Key

Add API key to header
Header: X-API-Key: your-key
Best for simple authentication

3. Bearer Token

Add bearer token to header
Header: Authorization: Bearer token
OAuth-style authentication

4. Custom Headers

Add custom headers
Multiple headers supported
Include any authentication info

5. Query Parameters

Include auth in URL
?api_key=your-key
Less secure, use HTTPS only

Test Webhook

Verify webhook configuration:

Click Test on webhook
Select sample event type
Configure test data
Send test payload
View response status
Check logs for delivery

Test Response:

Status: 200 OK
Time: 234ms
Response: {"success": true, "message": "Webhook processed"}

Webhook Delivery

Monitor webhook sends:

Delivery Features:

Real-time sending
Retry on failure
Queue management
Rate limiting
Timeout handling (30 seconds)

Success Criteria:

HTTP 2xx response
Response received within timeout
Valid JSON response (if expected)

Webhook Monitoring

Track outgoing webhook activity:

Go to CloudCusp Mailer → Webhooks → Outgoing
Click webhook to view details
View activity log
See delivery statistics

Monitoring Data:

Total events sent
Successful deliveries
Failed deliveries
Average response time
Last delivery status
Retry attempts

Webhook Logs

Detailed activity logging:

Log Entry Contains:

Event type triggered
Timestamp
Payload sent
External system response
Response time
HTTP status code
Error messages

CRM Integration Examples

Integrate with HubSpot

Sync subscribers with HubSpot:

Steps:

Create outgoing webhook
Set endpoint: https://api.hubapi.com/crm/v3/objects/contacts
Set auth: Authorization: Bearer hubspot-api-key
Configure events: subscriber_added, subscriber_updated
Map fields to HubSpot properties
Test connection
Activate webhook

Field Mapping:

CloudCusp → HubSpot
├─ first_name → firstname
├─ last_name → lastname
├─ email → email
├─ phone → phone
├─ company → company
└─ custom_field_id → hubspotutk

Integrate with Salesforce

Sync with Salesforce:

Steps:

Create outgoing webhook
Set endpoint: https://instance.salesforce.com/services/data/v57.0/sobjects/Contact
Set auth: OAuth token
Configure events
Map fields to Salesforce
Test connection
Activate webhook

Integrate with Zapier

Use Zapier for flexible integrations:

Flow:

Create incoming webhook in CloudCusp
Set up Zapier Catch Hook
Test webhook with Zapier
Create Zapier action (send to other apps)
Activate Zapier zap
Test integration

Zap Example:

Trigger: CloudCusp webhook received
  ↓
Filter: If status = "subscribed"
  ↓
Action: Create Google Sheets row
  ↓
Action: Send Slack notification

Custom Integration Development

Webhook API Reference

Use webhooks for custom integrations:

Webhook Header:

POST /webhook-endpoint HTTP/1.1
Host: yoursystem.com
Content-Type: application/json
Content-Length: 1234
X-Webhook-Signature: sha256=abcdef...

Expected Response:

json

{
  "success": true,
  "message": "Webhook processed successfully",
  "processed_records": 1
}

Best Practices

Verify Signature: Always verify webhook signature
Handle Duplicates: Implement idempotency
Fast Response: Return 200 within 10 seconds
Queue Processing: Process heavy operations async
Log Everything: Maintain detailed logs
Secure HTTPS: Always use HTTPS
Version API: Include API version
Test Thoroughly: Test all scenarios

Webhook Integration ​

Overview ​

Webhook Basics ​

What are Webhooks? ​

Incoming Webhooks ​

What are Incoming Webhooks? ​

Create Incoming Webhook ​

Incoming Event Types ​

Webhook Endpoint URL ​

Payload Structure ​

Webhook Actions ​

Field Mapping ​

Security Configuration ​

Retry Logic ​

Webhook Logs ​

Outgoing Webhooks ​

What are Outgoing Webhooks? ​

Create Outgoing Webhook ​

Outgoing Event Types ​

Webhook Payload Configuration ​

Authentication Methods ​

Test Webhook ​

Webhook Delivery ​

Webhook Monitoring ​

Webhook Logs ​

CRM Integration Examples ​

Integrate with HubSpot ​

Integrate with Salesforce ​

Integrate with Zapier ​

Custom Integration Development ​

Webhook API Reference ​

Best Practices ​

Webhook Integration

Overview

Webhook Basics

What are Webhooks?

Incoming Webhooks

What are Incoming Webhooks?

Create Incoming Webhook

Incoming Event Types

Webhook Endpoint URL

Payload Structure

Webhook Actions

Field Mapping

Security Configuration

Retry Logic

Webhook Logs

Outgoing Webhooks

What are Outgoing Webhooks?

Create Outgoing Webhook

Outgoing Event Types

Webhook Payload Configuration

Authentication Methods

Test Webhook

Webhook Delivery

Webhook Monitoring

Webhook Logs

CRM Integration Examples

Integrate with HubSpot

Integrate with Salesforce

Integrate with Zapier

Custom Integration Development

Webhook API Reference

Best Practices