Skip to content

Channel Web Hooks

Use channel web hooks when an external system needs to post content directly into an Emakin channel or create and update cases in that channel.

Web hooks are created from the channel properties and do not require a separate authentication flow once the generated URL is issued.

Typical Workflow

  1. Create a web hook in the target channel.
  2. Copy the generated URL.
  3. Post JSON payloads to that URL from the external system.
  4. Use a plain payload for activity messages, or include identifiers to create or update channel cases.

Create a New Web Hook

To create a new web hook:

  1. Open the channel where the integration should post messages.
  2. Select Edit from the channel menu.
  3. Open the Web Hooks tab and select Add New.
  4. Enter a purpose for the hook.
  5. Copy the generated URL with the Copy action.
  6. Save the channel changes.

Channel web hook settings with generated URL and purpose field.

Post Channel Activity

After the hook is created, post JSON data to create a new activity in the channel. The generated web-hook URL already contains the required identifying information.

Post a Basic Message

1
2
3
4
5
6
7
POST /hooks/channels/f923d83a-3350-42d0-b9cb-620032730294/8459b574-62ea-4ea7-bbae-a132fbfee5df
Host: my.emakin.com
Content-Type: application/json

{
    "text": "my message"
}

Basic channel web hook message result in the activity stream.

Post a Message with Attachments

The following payload posts a message with both file and link attachments:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
POST /hooks/channels/f923d83a-3350-42d0-b9cb-620032730294/8459b574-62ea-4ea7-bbae-a132fbfee5df
Host: my.emakin.com
Content-Type: application/json

{
    "text": "my message",
    "attachments": [
        {
            "@type": "file",
            "displayName": "my file",
            "ext": "txt",
            "url": "http://myserver/myfile"
        },
        {
            "@type": "link",
            "url": "http://www.google.com",
            "displayName": "http://www.google.com"
        }
    ]
}

Web hook message with file and link attachments inside the channel.

Create a New Case in a Channel

If the JSON payload contains an id property, the web hook creates a new case instead of only posting a message. The id must be unique within that channel. If the same id is posted again, the hook does not create a duplicate case.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
POST /hooks/channels/f923d83a-3350-42d0-b9cb-620032730294/8459b574-62ea-4ea7-bbae-a132fbfee5df
Host: my.emakin.com
Content-Type: application/json

{
    "id": "event1",
    "text": "my message",
    "attachments": [
        {
            "@type": "file",
            "displayName": "my file",
            "ext": "txt",
            "url": "http://myserver/myfile"
        },
        {
            "@type": "link",
            "url": "http://www.google.com",
            "displayName": "http://www.google.com"
        }
    ]
}

This payload creates a new case and attaches the message to that case.

Case created in a channel from a web hook message.

Update an Existing Case

To append a new message to an existing case, include a references array containing the previously reported case or message identifier.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
POST /hooks/channels/f923d83a-3350-42d0-b9cb-620032730294/8459b574-62ea-4ea7-bbae-a132fbfee5df
Host: my.emakin.com
Content-Type: application/json

{
    "id": "event2",
    "references": ["event1"],
    "text": "my message",
    "attachments": [
        {
            "@type": "file",
            "displayName": "my file",
            "ext": "txt",
            "url": "http://myserver/myfile"
        },
        {
            "@type": "link",
            "url": "http://www.google.com",
            "displayName": "http://www.google.com"
        }
    ]
}

This payload appends a new message to the existing case thread.

Existing case updated with a new web hook message.