# 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>**


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.klink.cloud/integrations/webhook-integration-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.