Web Hook

Overview

WebHook is used to call a particular Event back to your server for realtime processing.

Callback Format

It’s the HTTP POST request in JSON format with the request body like below:

{
    "timestamp": 1419123677382,
    "events": [
        { "name": "event_name", "some": "data" }
    ]
}

• timestamp: The Unix time stamp when WebHook is created.
• events: Including one or more Event, each Event contains name and the corresponding data. For more details, see the detailed explanation of each Event below:

Callback Error Handling

• Every callback has a 1-minute time-out limit.
• our server should return the 200 status code to indicate a successful reception.
• If an error occurs, including callback time-out or non-200 response code, Realtime Engine will retry with a 1-minute interval.
• A retry of at most 2 times, i.e., 3 callbacks in total.

Security

Encryption

You can use either HTTP or HTTPS as the WebHook address, but if your data is sensitive, or you hope to prevent replay attacks, please use HTTPS. There is no additional prolicy for data encryption for Realtime Engine at present.

If to use HTTPS, please make sure certificate trust chains are complete. The self-signed certificate will not be trusted by Realtime Engine.

Authentication

Theoretically, any one can send WebHook to your server. In order that you can verify whether a request comes from Reatime Engine, we add an X-Engine-Signature HEADER in the callback request, which is the HMAC SHA256 signature of the request body (serialized as JSON string) by using your Secret. After receiving the request, the same signature should be made, and then campared with X-Engine-Signature to verify the identity of the sender.

Pub/Sub Event

You can go to [Application]-> [Settings]-> [WebHook] to set the WebHook address as well as the Event type that needs to be called back.

Channel State Event

Notify your application when Channel is used or becomes empty.

Accordingly, you can publish Event only to the Channel with subscribers so as to save resources.

• channel_occupied: Triggered when Channel is changed to have subscribers (at lease one)from empty.

    {
        "name": "channel_occupied",
        "channel": "cool-channel"
    }
  

• channel_vacated: Triggered when Channel is changed from having subscribers to empty (0 subscriber)

    {
        "name": "channel_vacated",
        "channel": "cool-channel"
    }
  

Online State Event

It is triggered when users subscribe or unsubscribe Presence Channel.

You can implement the notifications of user’s coming online and going offline within the system accordingly.

• user_added: Triggered when users subscribe.

    {
        "name": "user_added",
        "channel": "presence-channel",
        "userId": "1122"
    }
  

• user_removed: Triggered when users unsubscribe.

    {
        "name": "user_removed",
        "channel": "presence-channel",
        "userId": "1122"
    }
  

Cient Event

Please stay tuned.

Chat Event

You can get the following Event notifications aftering adding the corresponding WebHook using Realtime Engine Open API.

Conversations

• message_new: Triggered when there are new messages.

    {
        "name": "message_new",
        "conversationId": "54c4951f50c5e752c0a512a1",
        "message": {
            "messageId": 300,
            // singleChat（Single chat） or groupChat（group chat）
            "type": "singleChat",
            // From whom，userId
            "from": "1111",
            // To whom，userId or groupId
            "to": "1112",
            "content": {
                // Content of text message
                "type": "text",
                "text": "Hello World!",
                "extra": {}
            }
        }
    }
  

• message_offline: Triggered when the message recipient is Offline (WebSocket connection unavailable)

    {
        "name": "message_offline",
        "conversationId": "54c4951f50c5e752c0a512a1",
        "message": {
            // message content, the same message structure as that in message_new
        },
        // There users are not online
        "offlineUserIds": ["1111", "1112"]
    }
  

Groups

• user_presence: Triggered when the online state of group members is changed.

    {
        "name": "user_presence",
        "groupId": "54c4951f50c5e752c0a512a1",
        "userId": "1111",
        // Changed to which state, online or offline
        "changedTo": "online"
    }