# Webhook Integration Guide

### Overview

klink.cloud provides **real-time webhook events** that allow external systems to receive **inbound and outbound chat messages** from your workspace.

Using webhooks, you can:

* Send chat notifications to **Slack** or **Microsoft Teams**
* Trigger workflows in **Zapier**, **Make.com**, or **n8n**
* Sync chat data with CRMs, ticketing systems, or internal tools
* Build custom automation or AI workflows

***

### Supported Automation Platforms

klink.cloud webhooks can be consumed by any HTTPS endpoint, including:

* **Zapier**
* **Make.com**
* **n8n (Cloud or Self-Hosted)**
* Custom backends (Node.js, Python, Go, PHP, etc.)

***

### Creating a Webhook in klink.cloud

1. Log in to **klink.cloud Admin Panel**
2. Navigate to **Settings → Developer Tools**
3. Click **Create App**
4. Configure:
   * **Webhook URL** (Zapier / Make / n8n endpoint)
   * **Webhook Events** (e.g. `message.inbound`, `message.outbound`)
5. Save the App

Once saved, klink.cloud will immediately start sending webhook events to the configured URL.

***

### Webhook Events

| Event              | Description                                   |
| ------------------ | --------------------------------------------- |
| `message.inbound`  | Triggered when a customer sends a message     |
| `message.outbound` | Triggered when an agent or AI sends a message |

***

### Webhook Request Specification

* **Method:** `POST`
* **Content-Type:** `application/json`
* **Payload Encoding:** UTF-8

#### Headers

```json
{
  "content-type": "application/json",
  "x-signature": "6ec15ebc99508d2b789b9a2dd8ae37388f108abfa277539fc374112cb6ee885d",
  "x-real-ip": "15.235.232.70"
}
```

#### Header Description

| Header         | Purpose                                  |
| -------------- | ---------------------------------------- |
| `x-signature`  | Webhook signature for request validation |
| `x-real-ip`    | Origin IP address                        |
| `content-type` | Always `application/json`                |

***

### Webhook Payload Example

#### Inbound Message (`message.inbound`)

```json
{
  "event": "message.inbound",
  "timestamp": "2025-12-23T11:16:55.943Z",
  "data": {
    "id": "39206a79-bc74-40c3-9dca-823f13cb7026",
    "type": "text",
    "direction": "incoming",
    "message": "thanks. ill think about it first",
    "createdAt": "2025-12-23T11:16:52.949Z",
    "contactId": "050823aa-8443-4fed-9951-f58d3b18c4eb",
    "roomId": "1f13f5d8-e426-42c7-9ce1-f50862f21965",
    "platformId": "waapi-66650491488@c.us",
    "room": {
      "isGroup": true,
      "isAiAgentRoom": true,
      "channel": {
        "type": "whatsapp",
        "name": "klink.cloud WA"
      },
      "lastMessage": "thanks. ill think about it first",
      "unreadCount": 5
    }
  }
}
```

***

### Key Payload Fields

#### Message Object (`data`)

| Field        | Description                            |
| ------------ | -------------------------------------- |
| `id`         | Unique message ID                      |
| `type`       | Message type (text, image, file, etc.) |
| `direction`  | incoming / outgoing                    |
| `message`    | Message content                        |
| `contactId`  | Customer contact ID                    |
| `roomId`     | Conversation ID                        |
| `platformId` | Messaging platform identifier          |

#### Room Object (`data.room`)

| Field           | Description                        |
| --------------- | ---------------------------------- |
| `isGroup`       | Group or 1-on-1 chat               |
| `isAiAgentRoom` | Chat handled by AI Agent           |
| `channel.type`  | whatsapp, livechat, telegram, etc. |
| `lastMessage`   | Latest message                     |
| `unreadCount`   | Number of unread messages          |

***

## Microsoft Teams Integration

klink.cloud webhook notifications can be sent to **Microsoft Teams** using Zapier, Make.com, or n8n.

### Authentication Options

#### Option A: Zapier / Make.com (Recommended)

Zapier and Make.com provide **built-in Microsoft authentication**.

✔ Users can authenticate using their **Microsoft Admin account**\
✔ No Azure app setup required\
✔ Fastest and easiest option

***

#### Option B: n8n Self-Hosted (Azure App Required)

For **n8n self-hosted**, users must register their own Microsoft OAuth application in **Microsoft Azure / Entra ID**.

***

### Microsoft Azure App Registration (n8n Self-Hosted)

#### Step 1: Register Application

1. Open **Microsoft Application Registration Portal**
2. Select **Register an application**
3. Enter an **Application Name**\
   \&#xNAN;*Example:* `klink-cloud-n8n-integration`

#### Step 2: Supported Account Types

Select:

> **Accounts in any organizational directory (Any Azure AD directory – Multi-tenant) and personal Microsoft accounts (e.g. Skype, Xbox)**

***

#### Step 3: Configure Redirect URI

4. In **n8n**, open Microsoft credential settings
5. Copy the **OAuth Callback URL**
6. In Azure:
   * Redirect URI → **Select a platform**
   * Choose **Web**
   * Paste the OAuth Callback URL
7. Click **Register**

***

#### Step 4: Configure Client ID in n8n

8. Copy the **Application (client) ID**
9. Paste it into n8n as the **Client ID**

Your n8n instance is now connected to Microsoft OAuth.

***

### Microsoft Permissions (Typical)

Depending on the workflow, admin consent may be required for:

* Microsoft Teams message posting
* Channel access
* User profile read access

Permission requirements depend on the n8n node and action used.

***

### Example Use Cases

* 🔔 Notify Sales team on new WhatsApp leads
* 🧑‍💼 Alert Support team on VIP messages
* 🤖 Trigger AI workflows on inbound messages
* 📊 Sync chat data to CRM or analytics tools

***

### Best Practices

* Always return **HTTP 200 OK** to acknowledge webhook receipt
* Process webhooks asynchronously
* Validate `x-signature` for security
* Use filters (channel, keyword, unread count) to reduce noise

***

### Supported Channels

* WhatsApp
* Live Chat
* Telegram
* Social Messaging
* Email (if enabled)

***

### Support

For integration help or questions:

* 📧 **<support@klink.cloud>**