Webhook Format Reference

v1.6.0+

Complete technical reference for WhatsMarkSaaS webhook payloads in N8N format.

Supported Resources

Resource	Description	Event Types
Contacts	Customer/contact records	`created`, `updated`, `deleted`
Sources	Lead sources	`created`, `updated`, `deleted`
Statuses	Contact statuses	`created`, `updated`, `deleted`

Base Payload Structure

All webhooks follow this standard structure:

json

{
  "event": {
    "id": "evt_{timestamp}_{random}",
    "type": "{resource}.{action}",
    "timestamp": "ISO 8601 datetime",
    "version": "1.0"
  },
  "tenant": {
    "id": integer,
    "name": "string",
    "domain": "string"
  },
  "data": {
    "resource": {
      "type": "contact|source|status",
      "id": integer,
      "attributes": { /* resource-specific fields */ }
    },
    "relationships": { /* related data */ }
  },
  "changes": {
    "previous": object|null,
    "current": object,
    "modified_fields": array|null
  },
  "metadata": {
    "source": "api_webhook_manager",
    "environment": "production",
    "request_id": "uuid"
  }
}

Event Types

Contact Events

Event Type	Description	When Triggered
`contact.created`	New contact created	Contact added via UI, API, or import
`contact.updated`	Contact modified	Any field updated
`contact.deleted`	Contact removed	Contact deleted permanently

Source Events

Event Type	Description	When Triggered
`source.created`	New source created	Lead source added
`source.updated`	Source modified	Source name or settings updated
`source.deleted`	Source removed	Source deleted

Status Events

Event Type	Description	When Triggered
`status.created`	New status created	Contact status added
`status.updated`	Status modified	Status name, color, or settings updated
`status.deleted`	Status removed	Status deleted

Contact Webhooks

Contact Created/Updated

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",
        "company": "Acme Inc",
        "type": "individual",
        "description": "Premium customer",
        "country_id": 1,
        "zip": "12345",
        "city": "New York",
        "state": "NY",
        "address": "123 Main St",
        "email": "[email protected]",
        "website": "https://example.com",
        "phone": "+1234567890",
        "is_enabled": true,
        "is_opted_out": false,
        "default_language": "en",
        "group_id": [5, 8],
        "custom_fields_data": {},
        "created_at": "2025-12-12T14:30:00.000000Z",
        "updated_at": "2025-12-12T14:30:00.000000Z"
      }
    },
    "relationships": {
      "status": {
        "id": 1,
        "name": "Active",
        "color": "#10b981"
      },
      "source": {
        "id": 2,
        "name": "Website"
      },
      "groups": [
        { "id": 5, "name": "VIP Customers" },
        { "id": 8, "name": "Newsletter" }
      ],
      "assigned_to": {
        "id": 10,
        "name": "Sarah Johnson",
        "email": "[email protected]"
      }
    }
  },
  "changes": {
    "previous": null,
    "current": { "firstname": "John", "lastname": "Doe" },
    "modified_fields": null
  },
  "metadata": {
    "source": "api_webhook_manager",
    "environment": "production",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Contact Deleted

json

{
  "event": {
    "id": "evt_1702468500_def456",
    "type": "contact.deleted",
    "timestamp": "2025-12-12T14:35: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]"
      }
    },
    "relationships": {}
  },
  "changes": {
    "previous": { "firstname": "John", "lastname": "Doe" },
    "current": null,
    "modified_fields": null
  },
  "metadata": {
    "source": "api_webhook_manager",
    "environment": "production",
    "request_id": "550e8400-e29b-41d4-a716-446655440001"
  }
}

Contact Attributes Reference

Field	Type	Description	Example
`firstname`	string	Contact first name	"John"
`lastname`	string	Contact last name	"Doe"
`company`	string	Company name	"Acme Inc"
`type`	string	Contact type	"individual" or "company"
`description`	string	Notes/description	"Premium customer"
`email`	string	Email address	"[email protected]"
`phone`	string	Phone number	"+1234567890"
`website`	string	Website URL	"https://example.com"
`address`	string	Street address	"123 Main St"
`city`	string	City	"New York"
`state`	string	State/province	"NY"
`zip`	string	Postal code	"12345"
`country_id`	integer	Country ID	1
`is_enabled`	boolean	Active status	true
`is_opted_out`	boolean	Marketing opt-out	false
`default_language`	string	Language code	"en"
`group_id`	array	Group IDs	[5, 8]
`custom_fields_data`	object	Custom field values	{}
`created_at`	string	Creation timestamp	"2025-12-12T14:30:00.000000Z"
`updated_at`	string	Last update timestamp	"2025-12-12T14:30:00.000000Z"

Source Webhooks

Source Created/Updated/Deleted

json

{
  "event": {
    "id": "evt_1702468400_ghi789",
    "type": "source.created",
    "timestamp": "2025-12-12T14:32:00.000Z",
    "version": "1.0"
  },
  "tenant": {
    "id": 123,
    "name": "Acme Corporation",
    "domain": "acme"
  },
  "data": {
    "resource": {
      "type": "source",
      "id": 7,
      "attributes": {
        "name": "Facebook Ads",
        "created_at": "2025-12-12T14:32:00.000000Z",
        "updated_at": "2025-12-12T14:32:00.000000Z"
      }
    },
    "relationships": {}
  },
  "changes": {
    "previous": null,
    "current": { "name": "Facebook Ads" },
    "modified_fields": null
  },
  "metadata": {
    "source": "api_webhook_manager",
    "environment": "production",
    "request_id": "550e8400-e29b-41d4-a716-446655440002"
  }
}

Source Attributes Reference

Field	Type	Description	Example
`name`	string	Source name	"Facebook Ads"
`created_at`	string	Creation timestamp	"2025-12-12T14:32:00.000000Z"
`updated_at`	string	Last update timestamp	"2025-12-12T14:32:00.000000Z"

Status Webhooks

Status Created/Updated/Deleted

json

{
  "event": {
    "id": "evt_1702468600_jkl012",
    "type": "status.created",
    "timestamp": "2025-12-12T14:33:00.000Z",
    "version": "1.0"
  },
  "tenant": {
    "id": 123,
    "name": "Acme Corporation",
    "domain": "acme"
  },
  "data": {
    "resource": {
      "type": "status",
      "id": 8,
      "attributes": {
        "name": "Hot Lead",
        "color": "#ef4444",
        "created_at": "2025-12-12T14:33:00.000000Z",
        "updated_at": "2025-12-12T14:33:00.000000Z"
      }
    },
    "relationships": {}
  },
  "changes": {
    "previous": null,
    "current": { "name": "Hot Lead", "color": "#ef4444" },
    "modified_fields": null
  },
  "metadata": {
    "source": "api_webhook_manager",
    "environment": "production",
    "request_id": "550e8400-e29b-41d4-a716-446655440003"
  }
}

Status Attributes Reference

Field	Type	Description	Example
`name`	string	Status name	"Hot Lead"
`color`	string	Hex color code	"#ef4444"
`created_at`	string	Creation timestamp	"2025-12-12T14:33:00.000000Z"
`updated_at`	string	Last update timestamp	"2025-12-12T14:33:00.000000Z"

Change Tracking

For updated events, the changes object provides detailed information about what changed:

Structure

json

{
  "changes": {
    "previous": {
      "email": "[email protected]",
      "phone": "+1111111111"
    },
    "current": {
      "email": "[email protected]",
      "phone": "+2222222222"
    },
    "modified_fields": ["email", "phone"]
  }
}

Fields

Field	Type	Description
`previous`	object	Old values of changed fields
`current`	object	New values of changed fields
`modified_fields`	array	List of field names that were modified

Change Detection

Use modified_fields array to quickly check which fields changed without comparing objects.

N8N Data Extraction

Basic Expressions

javascript

// Event information
{
  {
    $json.event.type;
  }
}
{
  {
    $json.event.timestamp;
  }
}

// Tenant information
{
  {
    $json.tenant.name;
  }
}
{
  {
    $json.tenant.domain;
  }
}

// Resource ID and type
{
  {
    $json.data.resource.id;
  }
}
{
  {
    $json.data.resource.type;
  }
}

Contact Data

javascript

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

// Contact details
{{ $json.data.resource.attributes.email }}
{{ $json.data.resource.attributes.phone }}
{{ $json.data.resource.attributes.company }}

// Address
{{ $json.data.resource.attributes.address }}, {{ $json.data.resource.attributes.city }}, {{ $json.data.resource.attributes.state }} {{ $json.data.resource.attributes.zip }}

Relationships

javascript

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

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

// Groups
{
  {
    $json.data.relationships.groups?.[0]?.name;
  }
}
{
  {
    $json.data.relationships.groups?.map((g) => g.name).join(', ');
  }
}

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

Change Detection

javascript

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

// Access old and new values
{
  {
    $json.changes.previous?.email;
  }
}
{
  {
    $json.changes.current?.email;
  }
}

// Count changed fields
{
  {
    $json.changes.modified_fields?.length;
  }
}

HTTP Headers

Every webhook request includes these headers:

Header	Description	Example
`Content-Type`	Request content type	`application/json`
`X-Webhook-Event`	Event type	`contact.created`
`X-Webhook-Timestamp`	Event timestamp	`2025-12-12T14:30:00+00:00`
`X-Webhook-Format`	Payload format	`n8n`

Accessing Headers in N8N

javascript

// Access headers
{
  {
    $json.headers['x-webhook-event'];
  }
}
{
  {
    $json.headers['x-webhook-timestamp'];
  }
}

Validation & Security

Event ID Format

Event IDs follow the pattern: evt_{unix_timestamp}_{random_string}

Example: evt_1702468200_abc123

Timestamp Format

All timestamps use ISO 8601 format with UTC timezone:

2025-12-12T14:30:00.000Z      (Event timestamp)
2025-12-12T14:30:00.000000Z   (Database timestamp)

Request ID

Each webhook includes a unique request_id (UUID v4) for tracing and debugging:

550e8400-e29b-41d4-a716-446655440000

Version History

v1.6.0 Current Format

N8N-optimized payload structure
Change tracking with previous/current values
Relationship data included
Standardized event metadata

INFO

The webhook format may evolve in future versions. Always check the event.version field in the payload.

N8N Webhook Integration Guide - Setup and examples
Webhook Management Settings - Configuration
N8N Documentation - N8N webhook node

Application Settings

System Settings

Setup & Configuration

Webhook Format Reference

Supported Resources

Base Payload Structure

Event Types

Contact Events

Source Events

Status Events

Contact Webhooks

Contact Created/Updated

Contact Deleted

Contact Attributes Reference

Source Webhooks

Source Created/Updated/Deleted

Source Attributes Reference

Status Webhooks

Status Created/Updated/Deleted

Status Attributes Reference

Change Tracking

Structure

Fields

N8N Data Extraction

Basic Expressions

Contact Data

Relationships

Change Detection

HTTP Headers

Accessing Headers in N8N

Validation & Security

Event ID Format

Timestamp Format

Request ID

Version History

Webhook Format Reference ​

Supported Resources ​

Base Payload Structure ​

Event Types ​

Contact Events ​

Source Events ​

Status Events ​

Contact Webhooks ​

Contact Created/Updated ​

Contact Deleted ​

Contact Attributes Reference ​

Source Webhooks ​

Source Created/Updated/Deleted ​

Source Attributes Reference ​

Status Webhooks ​

Status Created/Updated/Deleted ​

Status Attributes Reference ​

Change Tracking ​

Structure ​

Fields ​

N8N Data Extraction ​

Basic Expressions ​

Contact Data ​

Relationships ​

Change Detection ​

HTTP Headers ​

Accessing Headers in N8N ​

Validation & Security ​

Event ID Format ​

Timestamp Format ​

Request ID ​

Version History ​

Related Resources ​

Webhook Format Reference

Supported Resources

Base Payload Structure

Event Types

Contact Events

Source Events

Status Events

Contact Webhooks

Contact Created/Updated

Contact Deleted

Contact Attributes Reference

Source Webhooks

Source Created/Updated/Deleted

Source Attributes Reference

Status Webhooks

Status Created/Updated/Deleted

Status Attributes Reference

Change Tracking

Structure

Fields

N8N Data Extraction

Basic Expressions

Contact Data

Relationships

Change Detection

HTTP Headers

Accessing Headers in N8N

Validation & Security

Event ID Format

Timestamp Format

Request ID

Version History

Related Resources