v2

Webhooks

Webhooks are simple HTTP callbacks that allow you to subscribe to events that are happening inside Channelize.io Application. Rather than making an API call, Channelize.io can send an HTTP request to an endpoint that you configure when an event happens.

Supported Webhook Events

Below are the webhook events that we currently support. We will be adding more events in the future.

conversation.create - Triggers when a new conversation is initiated.

message.create - Triggers whenever a new message is sent in a conversation.

user.block - Triggers when a user is blocked by another user.

user.unblock - Triggers when a user is unblocked by another user.

conversation.add_members - Triggers when a new member is added to a conversation.

conversation.remove_members - Triggers when a member is removed from a conversation.

conversation.mark_as_read - Triggers When a user mark read to the conversation.

Use Cases

Find below some relevant and compelling Use-Cases of Webhooks. You can also suggest here what Use-Cases you want to use Webhooks for.

  1. Send custom new message notifications

    Using Channelize.io 'message.create' webhook build your custom notification service, such as an SMS or an email system for your offline users.

  2. Continuous Chat Backup & Monitoring

    Based on your Use-Case for messaging, you might want to maintain duplicate copies of all or selected messages on your server too. Using Channelize.io 'message.create' and 'conversation.create' webhooks you can save copies of such chats and messages on your server.

  3. Control unwanted Interactions

    You can avoid unwanted interactions on your platform for a user who is blocked by other users in Channelize.io. Use our 'user.block' and 'user.unblock' webhooks for the same.

  1. Custom Notifications for Group Admins

    Using Channelize.io 'conversation.add_members' and 'conversation.remove_members' webhooks you can build your custom notifications service to update Group Admins when a new member is added to a group or an existing member leaves a group.

Configure Webhooks

  • Login to your Channelize.io dashboard and navigate to the Webhooks section.
  • Click on Add Webhook.
  • Register your Endpoint URL where you want to receive the webhook payload.
  • Select the required events from the list of Events. You will receive the webhook payload for the events you have selected here.
  • Click on Save Changes to enable webhooks.
  • You can also Edit/ Delete or Enable/ Disable the webhooks. Edit Webhook will allow you to update the endpoint URL and selected events.

Webhook Endpoint Requirements

Your endpoint URL should meet the below requirements.

  1. The endpoint must support HTTP/1.1 and keep-alive.
  2. The endpoint needs to respond to POST requests.
  3. The endpoint needs to parse JSON payloads.
  4. The endpoint should respond to the webhook request with a 200 OK response within 5 seconds.

Failed Webhooks

If we receive a response code other than 200 for the webhook request, we will consider the webhook request as failed. For failed webhooks, we retry the webhook request 3 times in specific time interval.

Webhook Events

Currently, we only support a few events but we will be adding more events in the future.

EventDescription
pingWhen you Register/Enable/Update a webhook endpoint URL, Channelize.io checks if URL is active or not using ping event.
conversation.createWhen a new conversation is created in Channelize.io application.
message.createWhen a new message is sent, an existing message is forwarded or quoted/replied in Channelize.io application.
user.blockWhen a user is blocked by another user.
user.unblockWhen a user is unblocked by another user.
conversation.add_membersWhen a new member is added to a group conversation.
conversation.remove_membersWhen a member is removed from a group conversation.
conversation.mark_as_readWhen a user mark read to the conversation.

Webhook Payload

Webhook request contains the following headers and body:

Headers format

{
    "Content-Type": "application/json",
    "X-Channelize-Signature": "HASH_SIGNATURE"
}

X-Channelize-Signature in header contains a hash value and can be used for webhook security purpose.

Body

{
    "timestamp": "2019-08-09T13:12:56.787Z",
    "webhookId": "WEBHOOK_REQUEST_ID",
    "event": "conversation.create",
    "data": {
    }
}
ParameterDescription
timestampIndicates the time at which webhook was sent.
webhookIdIndicates the unique ID for each webhook request that you will receive.
eventIndicates the event's name for which webhook was called.
dataIndicates the event's data for a particular webhook request. It will be a conversation's object in case of 'conversation.create' event and message's object in case of 'message.create' event.

Payload for each of the webhook event is given below:

conversation.create

{
  "timestamp": "2020-01-29T12:22:42.423Z",
  "webhookId": "8d9f153f-87c6-4730-b69f-29537ecbc24b",
  "event": "conversation.create",
  "data": {
    "id": "6dab55dc-adeb-4d5d-b8ac-ad75958d76e9",
    "title": "Principal Applications Coordinator",
    "memberCount": 2,
    "isGroup": true,
    "ownerId": "20697",
    "profileImageUrl": "http://lorempixel.com/640/480",
    "createdAt": "2020-01-20T16:37:06.026Z",
    "type": "private",
    "customType": "messaging",
    "metaData": {},
    "lastReadAt": {
      "18859": "2020-01-20T16:37:06.026Z",
      "20697": "2020-01-20T16:37:06.026Z"
    },
    "members": [
      "18859",
      "20697"
    ]
  }
}

message.create

{
  "timestamp": "2020-01-29T12:24:45.918Z",
  "webhookId": "4c4d489a-da62-4b13-a6f1-2ba952cbf3ac",
  "event": "message.create",
  "data": {
    "id": "55904c80-4292-11ea-add6-7b417e62f421",
    "conversationId": "1021",
    "type": "normal",
    "createdAt": "2020-01-29T12:24:45.640Z",
    "updatedAt": "2020-01-29T12:24:45.640Z",
    "body": "Try to index the SSL capacitor, maybe it will generate the digital interface!",
    "ownerId": "20697",
    "attachments": [],
    "owner": {
      "id": "20697",
      "displayName": "alen joe",
      "profileImageUrl": "http://mobiledemodevelopment.s3.amazonaws.com/public/user/33/19/02/b5ceb45b2d6c74e4fc89673a5675c09c.jpg"
    },
    "mentionedUsers": []
  }
}

user.block

{
    "timestamp": "2020-01-06T11:19:43.972Z",
    "webhookId": "9b461914-2451-44e7-8e48-4b07bff47a60",
    "event": "user.block",
    "data": {
        "blocker": {
            "id": "35",
            "displayName": "Demo User 1",
            "profileImageUrl": "http://mobiledemodevelopment.s3.amazonaws.com/public/album_photo/88/3c/01/13a4d_e4d3.jpg",
            "profileUrl": "http://devaddons1.socialengineaddons.com/mobiledemodevelopment/profile/admin",
            "isOnline": true,
            "lastSeen": "2020-01-06T11:10:31.398Z"
        },
        "blockee": {
            "id": "20697",
            "displayName": "Demo User 2",
            "profileImageUrl": "http://mobiledemodevelopment.s3.amazonaws.com/public/user/33/19/02/b5ceb45b2d6c74e4fc89673a5675c09c.jpg",
            "profileUrl": "http://devaddons1.socialengineaddons.com/mobiledemodevelopment/profile/test1",
            "isOnline": false,
            "lastSeen": "2020-01-02T12:25:32.361Z"
        }
    }
}

user.unblock

{
    "timestamp": "2020-01-06T11:19:19.960Z",
    "webhookId": "3f83ed3c-44c8-4079-8564-03492d4d3361",
    "event": "user.unblock",
    "data": {
        "unblocker": {
            "id": "35",
            "displayName": "Demo User 1",
            "profileImageUrl": "http://mobiledemodevelopment.s3.amazonaws.com/public/album_photo/88/3c/01/13a4d_e4d3.jpg",
            "profileUrl": "http://devaddons1.socialengineaddons.com/mobiledemodevelopment/profile/admin",
            "isOnline": true,
            "lastSeen": "2020-01-06T11:10:31.398Z"
        },
        "unblockee": {
            "id": "20697",
            "displayName": "Demo User 2",
            "profileImageUrl": "http://mobiledemodevelopment.s3.amazonaws.com/public/user/33/19/02/b5ceb45b2d6c74e4fc89673a5675c09c.jpg",
            "profileUrl": "http://devaddons1.socialengineaddons.com/mobiledemodevelopment/profile/test1",
            "isOnline": false,
            "lastSeen": "2020-01-02T12:25:32.361Z"
        }
    }
}

conversation.add_members

{
  "timestamp": "2020-01-29T12:23:21.701Z",
  "webhookId": "fb6831d9-97a1-46e0-8234-82c8e720350b",
  "event": "conversation.add_members",
  "data": {
    "conversation": {
      "id": "6dab55dc-adeb-4d5d-b8ac-ad75958d76e9",
      "title": "Principal Applications Coordinator",
      "profileImageUrl": "http://lorempixel.com/640/480",
      "type": "private",
      "isGroup": true,
      "updatedAt": "2020-01-29T12:23:21.289Z",
      "memberCount": 2
    },
    "members": [
      {
        "id": "0bdf1850-4292-11ea-add6-7b417e62f421",
        "userId": "18859",
        "isAdmin": false,
        "user": {
          "id": "18859",
          "displayName": "sydney millers",
          "profileImageUrl": "http://mobiledemodevelopment.s3.amazonaws.com/public/user/17/0a/02/fbef1bb47eb85fb2979b135ed04e0eb3.png",
          "metaData": {
            "secondaryField": null
          },
          "profileUrl": "http://devaddons1.socialengineaddons.com/mobiledemodevelopment/profile/Alfredo",
          "isOnline": true,
          "notification": true,
          "lastSeen": "2020-01-29T12:14:23.346Z"
        }
      }
    ]
  }
}

conversation.remove_members

{
  "timestamp": "2020-01-29T12:23:18.008Z",
  "webhookId": "8d6e0f7b-d3ac-4e90-b1cd-960763d7c02b",
  "event": "conversation.remove_members",
  "data": {
    "conversation": {
      "id": "6dab55dc-adeb-4d5d-b8ac-ad75958d76e9",
      "title": "Principal Applications Coordinator",
      "profileImageUrl": "http://lorempixel.com/640/480",
      "type": "private",
      "isGroup": true,
      "updatedAt": "2020-01-29T12:23:17.589Z",
      "memberCount": 1
    },
    "members": [
      "18859"
    ]
  }
}

conversation.mark_as_read

{
  "timestamp": "2020-03-18T12:34:49.210Z",
  "webhookId": "1fd70e12-8265-4121-8f69-3172293eb7e9",
  "event": "conversation.mark_as_read",
  "data": {
    "conversation": {
      "id": "ffd8a440-5ede-11ea-86ea-c7a3c8e9c6d6",
      "type": "private",
      "isGroup": true,
      "title": "Hello 234 New 1",
      "profileImageUrl": "https://sample_cdn_url/1583413158259-groupPhoto.jpeg",
      "memberCount": 16,
      "metaData": {},
      "createdAt": "2020-03-05T12:44:05.636Z",
      "unreadMessageCount": 0
    },
    "user": {
      "id": "20697",
      "displayName": "Alen Joe",
      "profileImageUrl": "http://sample_cdn_url/b5ceb45b2d6c74e4fc89673a5675c09c.jpg",
      "metaData": {
          "secondaryField": "Engineer"
      },
      "profileUrl": "http://sample_website_url/profile/test1",
      "isOnline": false,
      "totalUnreadMessageCount": 32
    }
  }
}

Webhook Security

To validate the sent requests, Channelize.io sends a hash signature X-Channelize-Signature in the header. X-Channelize-Signature is generated using HMAC with SHA-256 algorithm with your private key as the key, and the webhook request payload as the message.

To validate the webhook request at your end, you need to convert the entire request body in JSON encoded string and create an HMAC SHA256 Signature using the private key. The signature should be compared with request header X-Channelize-Signature value. If these are equal, then the request is a valid request from Channelize.io.

A few code snippets to create signatures in some of the popular programming languages are mentioned below:

$body = json_encode($_POST);
$privateKey = 'YOUR_PRIVATE_KEY'
$signature = hash_hmac('sha256', $body, PRIVATE_KEY);
const crypto = require('crypto');
const body = JSON.stringify(REQUEST_BODY);
const privateKey = 'YOUR_PRIVATE_KEY';
const signature = crypto.createHmac('sha256', privateKey).update(body).digest('hex');

Tip: During development, developers can use various webhook testing websites. These websites provide endpoints that you can use as webhook endpoints and then check the request logs on these websites. A few of them are requestbin and webhook.site.

← ConversationsWebhooks API →