--- url: >- https://docs.corbitaltech.dev/products/whatsmark-saas/integrations/webhook-format-reference.md description: >- Technical reference for WhatsMarkSaaS webhook payload structure and N8N integration format. --- # Webhook Format Reference 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": "john@example.com", "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": "sarah@example.com" } } }, "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": "john@example.com" } }, "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 | "" | | `phone` | string | Phone number | "+1234567890" | | `website` | string | Website URL | "" | | `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": "old@example.com", "phone": "+1111111111" }, "current": { "email": "new@example.com", "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 | ::: tip 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 **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. ::: ## Related Resources * [N8N Webhook Integration Guide](./n8n-webhook-integration) - Setup and examples * [Webhook Management Settings](../tenant/webhook-management) - Configuration * [N8N Documentation](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.webhook/) - N8N webhook node