---
url: >-
  https://docs.corbitaltech.dev/products/whatsmark-saas/integrations/n8n-webhook-integration.md
description: >-
  Connect WhatsMarkSaaS with N8N workflows using webhook integration for
  automated contact, source, and status management.
---

# N8N Webhook Integration

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

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

::: tip 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)

::: warning 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

::: tip 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

::: tip 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:

```json
{
  "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": "john@example.com",
        "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:**

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

**Slack Message:**

```text
 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:**

```javascript
{
  {
    $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

```javascript
// 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

```javascript
// 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

```javascript
// 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:

```javascript
{
  {
    $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](./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:

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

### Conditional Routing

Route different event types to different workflows:

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

### Data Transformation

Transform webhook data before sending to other services:

```javascript
// 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](./webhook-format-reference) - Detailed payload documentation
* [Webhook Management Settings](../tenant/webhook-management) - Configuration guide
* [N8N Documentation](https://docs.n8n.io/) - Official N8N docs