Webhook Events and Schema

This page provides sample JSON payloads for all webhook events supported by the K-LINK Customer Support Platform. Use these schemas to understand the structure of incoming webhook requests and properly handle the data in your application.

Common Webhook Structure

All webhook requests follow this basic structure:

{
  "event": "event.type",
  "timestamp": "2026-01-09T03:42:38.000000Z",
  "data": {
    // Event-specific data
  }
}

Common Fields

Field	Type	Description
`event`	String	Type of event (e.g., `contact.create`, `message.inbound`)
`timestamp`	ISO 8601	When the event occurred in UTC
`data`	Object	Event-specific payload data

Contact Events

Contact Created

Triggered when a new contact is added to your system.

Event Type: contact.create

{
  "event": "contact.create",
  "timestamp": "2026-01-09T03:42:38.000000Z",
  "data": {
    "id": "a0cad4e8-c23b-426d-95fe-75d02325d943",
    "name": "John",
    "address": "No.123, Sik Rd, Singapore",
    "channel": "whatsapp",
    "company": null,
    "companyId": null,
    "contactEmails": [
      {
        "id": "a0cad4e8-d357-42ae-aea2-0f628b826bd6",
        "email": "john@klink.cloud",
        "isPrimary": true,
        "createdAt": "2026-01-09T03:42:38.000000Z",
        "updatedAt": "2026-01-09T03:42:38.000000Z",
        "deletedAt": null
      }
    ],
    "contactPhones": [
      {
        "id": "a0cad4e8-da82-4d6b-b11c-bd3338c5e5b4",
        "phone": "06838387278",
        "isPrimary": true,
        "createdAt": "2026-01-09T03:42:38.000000Z",
        "updatedAt": "2026-01-09T03:42:38.000000Z",
        "deletedAt": null
      }
    ],
    "contactNumber": null,
    "contactProfile": null,
    "socialProfileUrl": null,
    "notes": null,
    "customFields": [],
    "tags": [
      {
        "id": "4f9cdf9d-ad8f-46d9-8e37-116b8741a7fb",
        "name": "VVIP",
        "position": 0,
        "createdAt": "2024-04-01T03:07:53.577170Z",
        "updatedAt": "2025-05-29T06:46:18.717607Z",
        "deletedAt": null
      }
    ],
    "platformContacts": [],
    "createdAt": "2026-01-09T03:42:38.000000Z",
    "updatedAt": "2026-01-09T03:42:38.000000Z",
    "deletedAt": null
  }
}

Contact Create - Field Reference

Field	Type	Description
`id`	String	Unique contact identifier
`name`	String	Contact name
`address`	String	Physical address
`channel`	String	Primary communication channel
`company`	String/null	Company name
`companyId`	String/null	Associated company ID
`contactEmails`	Array	List of email addresses with `id`, `email`, `isPrimary`, timestamps
`contactPhones`	Array	List of phone numbers with `id`, `phone`, `isPrimary`, timestamps
`contactNumber`	Integer/null	Contact reference number
`contactProfile`	String/null	Profile image URL
`socialProfileUrl`	String/null	Social media profile URL
`notes`	String/null	Internal notes
`customFields`	Array	Custom field values
`tags`	Array	Assigned tags with `id`, `name`, `position`, timestamps
`platformContacts`	Array	Platform-specific contact data
`createdAt`	ISO 8601	Contact creation timestamp
`updatedAt`	ISO 8601	Last modification timestamp
`deletedAt`	ISO 8601/null	Soft delete timestamp

Contact Updated

Triggered when a contact's information is modified.

Event Type: contact.update

{
  "event": "contact.update",
  "timestamp": "2026-01-09T03:42:38.000000Z",
  "data": {
    "id": "a0cad4e8-c23b-426d-95fe-75d02325d943",
    "name": "John",
    "address": "No.123, Sik Rd, Singapore",
    "channel": "whatsapp",
    "company": null,
    "companyId": null,
    "contactEmails": [
      {
        "id": "a0cad4e8-d357-42ae-aea2-0f628b826bd6",
        "email": "john@klink.cloud",
        "isPrimary": true,
        "createdAt": "2026-01-09T03:42:38.000000Z",
        "updatedAt": "2026-01-09T03:42:38.000000Z",
        "deletedAt": null
      }
    ],
    "contactPhones": [
      {
        "id": "a0cad4e8-da82-4d6b-b11c-bd3338c5e5b4",
        "phone": "06838387278",
        "isPrimary": true,
        "createdAt": "2026-01-09T03:42:38.000000Z",
        "updatedAt": "2026-01-09T03:42:38.000000Z",
        "deletedAt": null
      }
    ],
    "contactNumber": 54432,
    "contactProfile": null,
    "socialProfileUrl": null,
    "notes": null,
    "customFields": [],
    "tags": [
      {
        "id": "4f9cdf9d-ad8f-46d9-8e37-116b8741a7fb",
        "name": "VVIP",
        "position": 0,
        "createdAt": "2024-04-01T03:07:53.577170Z",
        "updatedAt": "2025-05-29T06:46:18.717607Z",
        "deletedAt": null
      }
    ],
    "platformContacts": [],
    "createdAt": "2026-01-09T03:42:38.000000Z",
    "updatedAt": "2026-01-09T03:42:38.000000Z",
    "deletedAt": null
  }
}

Message Events

Inbound Message Received

Triggered when a new message is received from a customer.

Event Type: message.inbound

{
  "event": "message.inbound",
  "timestamp": "2026-01-09T07:05:42.378992489Z",
  "data": {
    "id": "706feaae-8e59-48c7-8784-33541e954c6b",
    "type": "text",
    "direction": "incoming",
    "message": "Hi there",
    "createdAt": "2026-01-09T07:05:33.027Z",
    "updatedAt": "2026-01-09T07:05:33.027Z",
    "editedAt": null,
    "isEdited": false,
    "platformMessageId": "m_doklox4t_bvRT60GJhQbji0VXumaYr7fHlifZ2Y4c5c-lSGsIQwFDjsNd5Uu8DaAyx2praGmIIa_zFwqswpEYQ",
    "platformId": "555104637677266",
    "roomId": "059e8ac4-50a5-4ecd-bb74-d63498ba709c",
    "senderId": null,
    "contactId": "9d15d54f-b876-445c-a6f7-ecf37cf1886b",
    "attachments": null,
    "readAt": null,
    "previewUrl": "",
    "locale": "",
    "template": null,
    "replyPlatformMessageId": null,
    "repliedMessage": null,
    "replyReaction": null,
    "metadata": {},
    "room": {
      "id": "059e8ac4-50a5-4ecd-bb74-d63498ba709c",
      "channelId": "4da39031-79b0-4fec-9800-4d9199ec82d5",
      "platformContactId": "7ea470eb-6e44-4f9d-aedd-e0330cb48235",
      "actorId": "8cde99fe-6054-4859-a104-d6a862afd811",
      "actor": {
        "id": "8cde99fe-6054-4859-a104-d6a862afd811",
        "name": "Hay Marn Sue",
        "email": "asue00630@gmail.com",
        "phone": "09980711651",
        "createdAt": "2023-11-17T09:12:08.801665Z",
        "updatedAt": "2025-12-24T09:16:25.826122Z",
        "deletedAt": null
      },
      "assigneeId": "8cde99fe-6054-4859-a104-d6a862afd811",
      "channel": {
        "id": "4da39031-79b0-4fec-9800-4d9199ec82d5",
        "name": "Testing Channel",
        "brandName": "Testing Channel",
        "type": "messenger",
        "platformId": "555104637677266",
        "status": true,
        "connectedUserId": "122131365806382390",
        "connectedUserName": "Jim Jim",
        "createdAt": "2025-12-15T05:55:14.275542Z",
        "updatedAt": "2025-12-15T05:55:14.275542Z",
        "deletedAt": null
      },
      "platformContact": [
        {
          "id": "7ea470eb-6e44-4f9d-aedd-e0330cb48235",
          "contactId": "9d15d54f-b876-445c-a6f7-ecf37cf1886b",
          "channelId": "4da39031-79b0-4fec-9800-4d9199ec82d5",
          "type": "messenger",
          "socialPlatformId": "25084025951204536",
          "metadata": {
            "id": "25084025951204536",
            "name": "John Hopper",
            "email": "",
            "profileUrl": "https://platform-lookaside.fbsbx.com/platform/profilepic/?psid=25084025951204536",
            "socialPlatformId": "25084025951204536",
            "contactFolderName": "demo/profile"
          },
          "createdAt": "2025-12-18T03:59:07.599301Z",
          "updatedAt": "2025-12-18T03:59:07.599301Z",
          "deletedAt": null
        }
      ],
      "direction": "incoming",
      "status": 1,
      "isLatest": true,
      "isBotRoom": false,
      "isGroup": false,
      "createdAt": "2025-12-18T03:59:03.39Z",
      "updatedAt": "2026-01-09T07:05:33.027Z",
      "firstResponseAt": "2025-12-18T04:38:13Z",
      "firstResponseTime": 0,
      "firstRepliedAt": null,
      "firstRepliedTime": null,
      "lastMessage": "Hi there",
      "lastMessageAt": "2026-01-09T07:05:33.027Z",
      "unreadCount": 1,
      "closedAt": null,
      "metadata": {}
    },
    "deletedAt": null
  }
}

Inbound Message - Field Reference

Field	Type	Description
`id`	String	Unique message identifier
`type`	String	Message type (e.g., `text`, `image`, `file`)
`direction`	String	`incoming` for inbound messages
`message`	String	Message body content
`createdAt`	ISO 8601	Message timestamp
`updatedAt`	ISO 8601	Last modification timestamp
`isEdited`	Boolean	Whether message was edited
`platformMessageId`	String	Platform-specific message ID
`platformId`	String	Platform account/page ID
`roomId`	String	Conversation room ID
`senderId`	String/null	ID of the sender (null for incoming)
`contactId`	String/null	Associated contact ID
`attachments`	Array/null	File attachments
`readAt`	ISO 8601/null	When message was read
`metadata`	Object	Platform-specific metadata and payload
`room`	Object	Associated room/conversation data
`deletedAt`	ISO 8601/null	Soft delete timestamp

Outbound Message Sent

Triggered when a message is sent to a customer.

Event Type: message.outbound

{
  "event": "message.outbound",
  "timestamp": "2026-01-09T07:07:38.128247406Z",
  "data": {
    "id": "c0ab2468-f630-4c75-9b8c-ba63df930b19",
    "type": "text",
    "direction": "outgoing",
    "message": "It is outbound message",
    "createdAt": "2026-01-09T07:07:34.699380286Z",
    "updatedAt": "2026-01-09T07:07:34.699380286Z",
    "editedAt": null,
    "isEdited": false,
    "platformMessageId": "m_ZDrWvRbfp_RwWyfAwc936S0VXumaYr7fHlifZ2Y4c5fYVVwxGqQYTwsZFdiZ6q4P2YIZxuB5Gr5395-X7jsZuA",
    "platformId": "555104637677266",
    "roomId": "059e8ac4-50a5-4ecd-bb74-d63498ba709c",
    "senderId": "d762a2be-ea27-49ff-b42c-03992953ab67",
    "contactId": "9d15d54f-b876-445c-a6f7-ecf37cf1886b",
    "attachments": null,
    "readAt": null,
    "previewUrl": "",
    "locale": "",
    "template": null,
    "replyPlatformMessageId": null,
    "repliedMessage": null,
    "replyReaction": null,
    "metadata": {},
    "room": {
      "id": "059e8ac4-50a5-4ecd-bb74-d63498ba709c",
      "channelId": "4da39031-79b0-4fec-9800-4d9199ec82d5",
      "platformContactId": "7ea470eb-6e44-4f9d-aedd-e0330cb48235",
      "actorId": "d762a2be-ea27-49ff-b42c-03992953ab67",
      "actor": {
        "id": "d762a2be-ea27-49ff-b42c-03992953ab67",
        "name": "John Hopper",
        "email": "johnhopper@gmail.co",
        "phone": "",
        "createdAt": "2023-11-22T18:40:10.632745Z",
        "updatedAt": "2025-05-01T04:04:12.691716Z",
        "deletedAt": null
      },
      "assigneeId": "d762a2be-ea27-49ff-b42c-03992953ab67",
      "assignee": {
        "id": "d762a2be-ea27-49ff-b42c-03992953ab67",
        "name": "John Hopper",
        "email": "johnhopper@gmail.co",
        "phone": "",
        "createdAt": "2023-11-22T18:40:10.632745Z",
        "updatedAt": "2025-05-01T04:04:12.691716Z",
        "deletedAt": null
      },
      "channel": {
        "id": "4da39031-79b0-4fec-9800-4d9199ec82d5",
        "name": "Testing Channel",
        "brandName": "Testing Channel",
        "type": "messenger",
        "platformId": "555104637677266",
        "status": true,
        "connectedUserId": "122131365806382390",
        "connectedUserName": "Jim Jim",
        "createdAt": "2025-12-15T05:55:14.275542Z",
        "updatedAt": "2025-12-15T05:55:14.275542Z",
        "deletedAt": null
      },
      "platformContact": [
        {
          "id": "7ea470eb-6e44-4f9d-aedd-e0330cb48235",
          "contactId": "9d15d54f-b876-445c-a6f7-ecf37cf1886b",
          "channelId": "4da39031-79b0-4fec-9800-4d9199ec82d5",
          "type": "messenger",
          "socialPlatformId": "25084025951204536",
          "metadata": {
            "id": "25084025951204536",
            "name": "John Hopper",
            "email": "",
            "profileUrl": "https://platform-lookaside.fbsbx.com/platform/profilepic/?psid=25084025951204536",
            "socialPlatformId": "25084025951204536",
            "contactFolderName": "demo/profile"
          },
          "createdAt": "2025-12-18T03:59:07.599301Z",
          "updatedAt": "2025-12-18T03:59:07.599301Z",
          "deletedAt": null
        }
      ],
      "cxLog": {
        "id": "313111f6-3c40-4a01-b9ca-be56f4cd265f",
        "caseId": 13315,
        "channel": "messenger",
        "direction": "inbound",
        "contactId": "9d15d54f-b876-445c-a6f7-ecf37cf1886b",
        "agentId": "d762a2be-ea27-49ff-b42c-03992953ab67",
        "firstAssigneeId": "8cde99fe-6054-4859-a104-d6a862afd811",
        "entityName": "room",
        "entityId": "059e8ac4-50a5-4ecd-bb74-d63498ba709c",
        "startedDate": "2025-12-18T03:59:03.39Z",
        "firstResponseTime": 0,
        "firstRepliedTime": null,
        "createdAt": "2025-12-18T03:59:08.628432Z",
        "updatedAt": "2026-01-09T07:07:18Z",
        "wrapUpFormId": "f71c0570-f92e-426e-9017-6c64cb75bc0b",
        "deletedAt": null
      },
      "direction": "incoming",
      "status": 1,
      "isLatest": true,
      "isBotRoom": false,
      "isGroup": false,
      "createdAt": "2025-12-18T03:59:03.39Z",
      "updatedAt": "2026-01-09T07:07:34.69938Z",
      "firstResponseAt": "2025-12-18T04:38:13Z",
      "firstResponseTime": 0,
      "firstRepliedAt": "2026-01-09T07:07:37.085254Z",
      "firstRepliedTime": 1912113,
      "lastMessage": "It is outbound message",
      "lastMessageAt": "2026-01-09T07:05:33.027Z",
      "unreadCount": 0,
      "closedAt": null,
      "metadata": {}
    },
    "deletedAt": null
  }
}

Outbound Message - Field Reference

Field	Type	Description
`id`	String	Unique message identifier
`type`	String	Message type (e.g., `text`, `image`, `file`)
`direction`	String	`outgoing` for outbound messages
`message`	String	Message body content
`createdAt`	ISO 8601	Message timestamp
`updatedAt`	ISO 8601	Last modification timestamp
`isEdited`	Boolean	Whether message was edited
`platformMessageId`	String	Platform-specific message ID
`platformId`	String	Platform account/page ID
`roomId`	String	Conversation room ID
`senderId`	String	ID of the agent/user who sent the message
`contactId`	String	Associated contact ID
`attachments`	Array/null	File attachments
`readAt`	ISO 8601/null	When message was read by recipient
`metadata`	Object	Custom metadata (can be empty)
`replyPlatformMessageId`	String/null	ID of replied message on platform
`repliedMessage`	Object/null	Replied message content
`replyReaction`	String/null	Reaction to message
`room`	Object	Associated room/conversation data with metrics and cxLog
`deletedAt`	ISO 8601/null	Soft delete timestamp

Room Object Reference

The room object contains conversation context and appears in message events:

Field	Type	Description
`id`	String	Unique room/conversation ID
`channelId`	String	Associated channel ID
`platformContactId`	String	Platform contact identifier
`assigneeId`	String/null	Assigned agent/user ID
`direction`	String	`incoming` or `outgoing`
`status`	Integer	Room status (1 = active)
`isLatest`	Boolean	Whether this is the latest conversation
`createdAt`	ISO 8601	Conversation creation timestamp
`updatedAt`	ISO 8601	Last activity timestamp
`firstRepliedAt`	ISO 8601/null	When first response was sent
`firstRepliedTime`	Integer	Milliseconds to first reply
`firstResponseAt`	ISO 8601/null	When first message was received
`firstResponseTime`	Integer	Milliseconds to first response
`lastMessage`	String	Last message text
`lastMessageAt`	ISO 8601	Timestamp of last message
`unreadCount`	Integer	Number of unread messages

Email Object Reference

Appears in the contactEmails array:

Field	Type	Description
`id`	String	Unique email ID
`email`	String	Email address
`isPrimary`	Boolean	Primary email flag
`createdAt`	ISO 8601	Creation timestamp
`updatedAt`	ISO 8601	Last modification timestamp
`deletedAt`	ISO 8601/null	Soft delete timestamp

Phone Object Reference

Appears in the contactPhones array:

Field	Type	Description
`id`	String	Unique phone ID
`phone`	String	Phone number
`isPrimary`	Boolean	Primary phone flag
`createdAt`	ISO 8601	Creation timestamp
`updatedAt`	ISO 8601	Last modification timestamp
`deletedAt`	ISO 8601/null	Soft delete timestamp

Tag Object Reference

Appears in the tags array:

Field	Type	Description
`id`	String	Unique tag ID
`name`	String	Tag name
`position`	Integer	Display position/order
`createdAt`	ISO 8601	Creation timestamp
`updatedAt`	ISO 8601	Last modification timestamp
`deletedAt`	ISO 8601/null	Soft delete timestamp

Best Practices for Handling Payloads

Validate Signature: Always verify webhook signatures before processing payload data

Handle Null Values: Optional fields may be null; use defensive programming

Parse Timestamps: All timestamps are in ISO 8601 format with UTC timezone

Store Event IDs: Track processed message IDs to avoid duplicate processing

Idempotency: Use clientRequestId for outbound messages to detect retries

Room Context: Use room object data for conversation metrics and status

Custom Fields: The customFields array structure depends on your workspace configuration

Metadata: Platform-specific data is nested in the metadata object; parse based on channel type

Testing with Sample Data

To test your webhook handler without live events, you can:

Copy the sample payloads above

Test your signature verification with these payloads

Ensure your endpoint correctly parses and processes the data

Verify error handling for edge cases

Validate timestamp parsing and timezone handling

For more information about webhook setup, refer to the Webhook Setup Documentation.

Common Webhook Structure#

Common Fields#

Contact Events#

Contact Created#

Contact Create - Field Reference#

Contact Updated#

Message Events#

Inbound Message Received#

Inbound Message - Field Reference#

Outbound Message Sent#

Outbound Message - Field Reference#

Room Object Reference#

Email Object Reference#

Phone Object Reference#

Tag Object Reference#

Best Practices for Handling Payloads#

Testing with Sample Data#