N8N Webhook Integration

v1.6.0+

Automate your workflows by connecting WhatsMarkSaaS with N8N. Track changes to contacts, sources, and statuses in real-time and trigger automated actions across your business tools.

• Overview
• Supported Events
• Quick Start
  • Step 1: Enable Webhooks in WhatsMarkSaaS
  • Step 2: Create Webhook in N8N
  • Step 3: Configure Webhook URL
  • Step 4: Test the Connection
• Webhook Payload Structure
  • Key Fields Explained
• N8N Workflow Examples
  • Example 1: New Contact Notification to Slack
  • Example 2: Sync Contacts to Google Sheets
  • Example 3: Status Change Alert
• Extracting Data in N8N
  • Contact Information
  • Relationships
  • Change Tracking
• HTTP Headers
• Best Practices
  • 1. Filter Events Early
  • 2. Handle Errors Gracefully
  • 3. Avoid Rate Limits
  • 4. Test with Real Data
  • 5. Monitor Webhook Deliveries
• Troubleshooting
  • Webhook Not Received
  • Incorrect Data Format
  • Authentication Errors
• Advanced Use Cases
  • Multi-Tenant Workflows
  • Conditional Routing
  • Data Transformation
• Related Resources

Overview

The Webhook Integration feature sends real-time notifications to N8N whenever important events occur in your WhatsMarkSaaS tenant. This enables you to:

• 🔄 Sync contacts to Google Sheets, CRMs, or databases
• 📧 Send notifications via Slack, email, or SMS
• 🤖 Trigger workflows based on status changes
• 📊 Update analytics dashboards in real-time
• 🔗 Connect with 400+ apps supported by N8N

Version Requirement

N8N integration support was introduced in version 1.6.0. The webhook payload format is now fully optimized for N8N workflows.

Supported Events

WhatsMarkSaaS can send webhooks for the following resources:

Resource	Events	Description
Contacts	created, updated, deleted	Customer and lead records
Sources	created, updated, deleted	Lead source tracking
Statuses	created, updated, deleted	Contact status tracking

Quick Start

Step 1: Enable Webhooks in WhatsMarkSaaS

1. Log into your tenant account
2. Navigate to Settings → System Settings → Webhook Management
3. Toggle Enable Webhooks to ON
4. Select the events you want to track:
   • ✅ Contact Actions (create, update, delete)
   • ✅ Source Actions (create, update, delete)
   • ✅ Status Actions (create, update, delete)

Save Your Settings

Don't forget to click Save after configuring your webhook events.

Step 2: Create Webhook in N8N

1. Open your N8N workflow editor
2. Add a Webhook node to your workflow
3. Configure the node:
   • HTTP Method: POST
   • Path: Choose a unique path (e.g., /whatsmark-webhooks)
   • Authentication: None (or configure as needed)
4. Copy the generated webhook URL

N8N Setup

You can find the Webhook node in the Core Nodes section of N8N. The webhook URL will be automatically generated once you save the workflow.

Step 3: Configure Webhook URL

Back in WhatsMarkSaaS:

1. Go to Settings → System Settings → Webhook Management
2. Paste your N8N webhook URL in the Webhook URL field
3. Click Save

Step 4: Test the Connection

1. Create a new contact in WhatsMarkSaaS
2. Check your N8N workflow - it should receive the webhook
3. Inspect the payload to verify the data structure

Testing

Use N8N's Execute Node feature to test your webhook without waiting for real events.

Webhook Payload Structure

Every webhook sent to N8N follows this standardized format:

{
  "event": {
    "id": "evt_1702468200_abc123",
    "type": "contact.created",
    "timestamp": "2025-12-12T14:30:00.000Z",
    "version": "1.0"
  },
  "tenant": {
    "id": 123,
    "name": "Acme Corporation",
    "domain": "acme"
  },
  "data": {
    "resource": {
      "type": "contact",
      "id": 456,
      "attributes": {
        "firstname": "John",
        "lastname": "Doe",
        "email": "[email protected]",
        "phone": "+1234567890",
        "company": "Acme Inc"
      }
    },
    "relationships": {
      "status": {
        "id": 1,
        "name": "Active"
      },
      "source": {
        "id": 2,
        "name": "Website"
      }
    }
  },
  "changes": {
    "previous": null,
    "current": { "firstname": "John", "lastname": "Doe" },
    "modified_fields": null
  }
}

Key Fields Explained

• event: Metadata about the webhook event

  • type: Event identifier (e.g., contact.created, status.updated)
  • timestamp: When the event occurred (ISO 8601 format)

• tenant: Information about your WhatsMarkSaaS tenant

• data: The actual resource data

  • resource.attributes: Direct properties of the resource
  • relationships: Related data (status, source, groups, etc.)

• changes: For updated events only

  • previous: Old values
  • current: New values
  • modified_fields: Array of changed field names

N8N Workflow Examples

Example 1: New Contact Notification to Slack

Send a Slack message whenever a new contact is created.

Workflow Nodes:

1. Webhook - Receive webhook from WhatsMarkSaaS
2. IF - Filter for contact creation events
3. Slack - Send notification

IF Node Expression:

{
  {
    $json.event.type === 'contact.created';
  }
}

Slack Message:

🎉 New Contact Added!

Name: {{ $json.data.resource.attributes.firstname }} {{ $json.data.resource.attributes.lastname }}
Email: {{ $json.data.resource.attributes.email }}
Phone: {{ $json.data.resource.attributes.phone }}
Source: {{ $json.data.relationships.source.name }}
Status: {{ $json.data.relationships.status.name }}

Example 2: Sync Contacts to Google Sheets

Automatically add new contacts to a Google Sheet.

Workflow Nodes:

1. Webhook - Receive webhook
2. IF - Filter for contact.created
3. Google Sheets - Append row

Google Sheets Configuration:

• Column A: {{ $json.data.resource.id }}
• Column B: {{ $json.data.resource.attributes.firstname }}
• Column C: {{ $json.data.resource.attributes.lastname }}
• Column D: {{ $json.data.resource.attributes.email }}
• Column E: {{ $json.data.resource.attributes.phone }}
• Column F: {{ $json.data.relationships.status.name }}
• Column G: {{ $json.data.relationships.source.name }}
• Column H: {{ $json.event.timestamp }}

Example 3: Status Change Alert

Get notified when a contact becomes a "Hot Lead".

Workflow Nodes:

1. Webhook - Receive webhook
2. IF - Check for status change to "Hot Lead"
3. Send Email - Alert sales team

IF Node Expression:

{
  {
    $json.event.type === 'contact.updated' &&
      $json.changes.modified_fields?.includes('status_id') &&
      $json.data.relationships.status.name === 'Hot Lead';
  }
}

Extracting Data in N8N

Use these expressions to access webhook data in your N8N workflows:

Contact Information

// Full name
{
  {
    $json.data.resource.attributes.firstname;
  }
}
{
  {
    $json.data.resource.attributes.lastname;
  }
}

// Email
{
  {
    $json.data.resource.attributes.email;
  }
}

// Phone
{
  {
    $json.data.resource.attributes.phone;
  }
}

// Company
{
  {
    $json.data.resource.attributes.company;
  }
}

Relationships

// Status name
{
  {
    $json.data.relationships.status.name;
  }
}

// Source name
{
  {
    $json.data.relationships.source.name;
  }
}

// First group name
{
  {
    $json.data.relationships.groups[0]?.name;
  }
}

// All groups (comma-separated)
{
  {
    $json.data.relationships.groups?.map((g) => g.name).join(', ');
  }
}

// Assigned to
{
  {
    $json.data.relationships.assigned_to?.name;
  }
}

Change Tracking

// Check if email changed
{
  {
    $json.changes.modified_fields?.includes('email');
  }
}

// Previous email value
{
  {
    $json.changes.previous?.email;
  }
}

// Current email value
{
  {
    $json.changes.current?.email;
  }
}

HTTP Headers

WhatsMarkSaaS includes these headers with every webhook request:

Content-Type: application/json
X-Webhook-Event: contact.created
X-Webhook-Timestamp: 2025-12-12T14:30:00+00:00
X-Webhook-Format: n8n

You can use these headers in N8N for additional validation or routing logic.

Best Practices

1. Filter Events Early

Use IF nodes at the start of your workflow to filter only the events you need:

{
  {
    $json.event.type === 'contact.created' ||
      $json.event.type === 'contact.updated';
  }
}

2. Handle Errors Gracefully

Add error handling nodes to prevent workflow failures:

• Use Try/Catch blocks
• Set up Error Workflow in N8N settings

3. Avoid Rate Limits

If processing large volumes:

• Use Batch nodes to group operations
• Add Wait nodes between API calls
• Consider using Queue nodes for async processing

4. Test with Real Data

Always test your workflow with actual webhook data before deploying to production.

5. Monitor Webhook Deliveries

Check your webhook logs in WhatsMarkSaaS:

• Go to Settings → System Settings → Webhook Management
• View delivery history and error logs

Troubleshooting

Webhook Not Received

Check N8N:

• ✅ Workflow is activated
• ✅ Webhook node is properly configured
• ✅ URL is publicly accessible (not localhost)

Check WhatsMarkSaaS:

• ✅ Webhooks are enabled
• ✅ Correct URL is configured
• ✅ Events are selected
• ✅ Check webhook logs for errors

Incorrect Data Format

• ✅ Verify you're using version 1.6.0 or higher
• ✅ Check the Webhook Format Reference for detailed payload structure
• ✅ Use N8N's Execute Node to inspect raw payload

Authentication Errors

If using webhook authentication in N8N:

• ✅ Configure matching authentication in WhatsMarkSaaS
• ✅ Use header-based auth (Basic or Bearer tokens)

Advanced Use Cases

Multi-Tenant Workflows

Filter webhooks by tenant:

{
  {
    $json.tenant.domain === 'your-tenant-name';
  }
}

Conditional Routing

Route different event types to different workflows:

// Route by event type
{
  {
    $json.event.type.startsWith('contact.')
      ? 'contact-workflow'
      : 'other-workflow';
  }
}

Data Transformation

Transform webhook data before sending to other services:

// Create custom payload
{{
  {
    "full_name": $json.data.resource.attributes.firstname + ' ' + $json.data.resource.attributes.lastname,
    "contact_email": $json.data.resource.attributes.email,
    "lead_source": $json.data.relationships.source.name
  }
}}

Related Resources

• Webhook Format Reference - Detailed payload documentation
• Webhook Management Settings - Configuration guide
• N8N Documentation - Official N8N docs