This guide explains how to manage external applications with kChat using webhooks.

Introduction

• A webhook is a method that allows an application to be notified immediately when a specific event occurs in another application, rather than constantly asking that application if anything new has happened ("polling").
  • Outgoing webhook: kChat communicates information to other apps when an event occurs in kChat.
  • Incoming webhook: kChat receives information from other apps to trigger actions in kChat.
• It is not possible to import the history of discussions from another application (Slack, Teams, Jabber, etc.) or from another Organization.
• Maximum number of incoming/outgoing Webhooks:
  • kSuite Free = 1 / 1
  • kSuite Standard = 20 / 20
  • kSuite Business = unlimited
  • kSuite Enterprise = unlimited

Accessing the kChat webhooks interface

Prerequisites

• You must not be an external user (they will not see the Integrations menu).

To configure a webhook, find self-hosted or third-party applications and integrations:

1. Click here to access the kChat web app (online service ksuite.infomaniak.com/kchat) or open the kChat desktop app (desktop application on macOS / Windows / Linux).
2. Click on the New icon ‍ next to your kChat organization's name.
3. Click on Integrations:
   
4. Access the categories:
   

Specific guides

Examples of integration on kChat:

• Calendar Infomaniak: display an event reminder on kChat
• n8n application: trigger the sending of a message on kChat

Guides for other uses

To create an incoming webhook (to display an external event on kChat):

1. Click on the Incoming Webhooks category.
2. Click on the blue Add incoming webhooks button:
   
3. Add a name and description for the webhook.
4. Select the channel that will receive the messages.
5. Click the button to Save:
   
6. The URL to keep for your developments is displayed (do not disclose it publicly); example: “https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx”:
   

Using the webhook

Quick example

1. A specific curl command (detailed below) is entered into a terminal.
2. The command contains the URL obtained in step 6 above.
3. The command will post a message in the channel specified in step 4 above:
   

Details

Regarding the application that will post on kChat:

1. Adjust the code below based on the URL obtained from kChat:

   POST /hooks/xxx-key-generated-xxx HTTP/1.1
   Host: your-server-kchat.xyz
   Content-Type: application/json
   Content-Length: 63
   {
       "text": "Hello, text1\nText2."
   }

2. If necessary, use the same request but with curl (to test from a Terminal application (command-line interface, CLI) on your device), as in the example image above:

   curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "Hello, text1\nText2."}' {{URL_12}}

If no Content-Type header is defined, the request body must be preceded by payload= as follows:

payload={"text": "Hello, text1\nText2."}

A successful request will receive the following response:

HTTP/1.1 200 OK	
Content-Type: application/json	
X-Version-Id: 4.7.1.dev.12799dvd77e172e8a2eba0f4041ec1471.false	
Date: Sun, 01 Jun 2023 17:00:00 GMT	
Content-Length: 58	
	
{	
    "id":"x",	
    "create_at":1713198308869,	
    "update_at":1713198308869,	
    "delete_at":0,	
    "user_id":"x",	
    "channel_id":"x",	
    "root_id":"",	
    "original_id":"",	
    "participants":null,	
    "message":"test",	
    "type":"",	
    "props":{	
        "override_username":"webhook",	
        "override_icon_url":null,	
        "override_icon_emoji":null,	
        "webhook_display_name":"test",	
        "attachments":[	
	
        ],	
        "card":null,	
        "from_webhook":"true"	
    },	
    "hashtags":null,	
    "metadata":{	
        "embeds":[	
            {	
                "type":"message_attachment"	
            }	
        ],	
        "files":[	
	
        ],	
        "reactions":[	
	
        ]	
    },	
    "file_ids":null,	
    "has_reactions":false,	
    "edit_at":0,	
    "is_pinned":false,	
    "remote_id":null,	
    "reply_count":0,	
    "pending_post_id":null,	
    "is_following":false	
}

If you want to have the same response format as Slack:

HTTP/1.1 200 OK
Content-Type: text/plain
X-Request-Id: hoan69ws7rp5xj7wu9rmystry
X-Version-Id: 4.7.1.dev.12799dvd77e172e8a2eba0f4041ec1471.false
Date: Sun, 01 Jun 2023 17:00:00 GMT
Content-Length: 2
ok

You must add ?slack_return_format=true to the webhook URL.

Parameters

In addition to the text field, here is the complete list of supported parameters:

Code example with parameters

Here's how to generate a more complete message with parameters, some of which can replace parameters already defined when creating the webhook (username, preferred channel, avatar, etc.), as shown in the table above:

curl -i -X POST -H 'Content-Type: application/json' \
-d '{
"username": "System Monitor",
  "icon_url": "{{URL_13}}",
  "text": "### System Status Report\nEnvironment: PRODUCTION\nStatus: SUCCESSFUL\n\n---\n\n| Component | Version | Build ID | Status |\n|:----------|:-------:|:---------|:-------|\n| API-Core  | 2.4.1   | #88421   | OK     |\n| Web-UI    | 1.9.0   | #88425   | OK     |\n| Database  | 14.5    | N/A      | OK     |\n\n---\n\n**Commit Reference:**\n`git-ref: a7f8e9c21b` \n\n**Summary:**\nAll automated integration tests passed successfully. No manual intervention is required. Please contact the DevOps team for further details regarding this release."
}' \
{{URL_14}}

Result of a similar example in the image: