Webhooks

Please make sure your Core Version is v2.2 or above in order to apply webhooks. You can check the Core Version in "Trees" -> "Settings" in channel.

Validation

All the webhook event would come with a signature ("X-Stella-Signature") in the header for validation purposes. Each webhook event could be validated using the following method.

1. Using the HMAC-SHA256 algorithm with the channel secret as the secret key, compute the digest for the request body.
2. Confirm that the Base64-encoded digest matches the signature in the X-Stella-Signature request header.

Inbound Messages

Stella would relay all the events it receives to your designated webhook in 2 forms.

Raw Inbound Messages

By subscribing to this webhook, your would receive the raw events that we are receiving. Noted that on Messenger, the event structure would be slightly different from the raw event received from Messenger (which was an array).

Sample from WhatsApp

Text

{
  "contacts": [
    {
      "profile": {
        "name": "Roy"
      },
      "wa_id": "85260903521"
    }
  ],
  "messages": [
    {
      "from": "85260903521",
      "id": "ABGGhSYJA1IfAgo6qRe8bWPLEpxD",
      "text": {
        "body": "Hello"
      },
      "timestamp": "1599536864",
      "type": "text"
    }
  ]
}

Video

{
  "contacts": [
    {
      "profile": {
        "name": "Roy"
      },
      "wa_id": "85260903521"
    }
  ],
  "messages": [
    {
      "from": "85260903521",
      "id": "ABGGhSYJA1IfAgo6koySp3Sro3ro",
      "timestamp": "1599537042",
      "type": "video",
      "video": {
        "id": "e8a85916-2386-49dc-8f05-1cd0527bfb68",
        "mime_type": "video/mp4",
        "sha256": "586cc370c535661c16e662f9cd2987215a878efd929073230de7cf5ec0c867ff"
      }
    }
  ]
}

Normalized Inbound Messages

By subscribing to this webhook, your would receive the normalized events that Stella pre-processed for all supported platforms.

Sample from WhatsApp

Text

{
  "from": "85260903521",
  "to": "85268227287",
  "timestamp": "1599536864",
  "type": "TEXT",
  "data": {
    "text": "Hello"
  }
}

Video

{
  "from": "85260903521",
  "to": "85268227287",
  "timestamp": "1599536864",
  "type": "MISC",
  "data": {
    "attachments": [{
      "type": "VIDEO",
      "waMediaId": "e8a85916-2386-49dc-8f05-1cd0527bfb68",
    }],
  }
}

Outbound Mesages

Bot Replied Messages

When the member (end-user) liveChat property is false, Stella would send the messages sent by chatbot to your designated webhook.

Manual Messages

All the messages sent via Stella sendResponse API would also send to your designated webhook as type MANUAL.

Relay Messages

When the member (end-user) liveChat property is true, Stella would relay the messages from and to the corresponding pairing channels, and these messages would be send to your designated webhook as type RELAY.

body

Property	Type	Description
type	String	Can be either BOT, MANUAL or RELAY. Indicating whether the outbound message is from the chatbot or from API
messageEvent	Object	messageEvent object container the normalised message
app	String	ID of the app
channel	String	ID of the chanel

messageEvent

Property	Type	Description
from	String	ID of the sender
to	String	ID of the receipient
timestamp	Number	Unix timestamp
type	String	Message type*
data	Object	Message data for the corresponding message type*
messageId	String	Message ID from the external platform (this property might not exists)

*Please refer to the official documentation for all the message types and the structure of the corresponding message data.

Sample event

{
  type: "BOT",
  app: "app-id",
  channel: "channel-id",
  messageEvent: {
    from: "1332323131312",
    to: "443232332323",
    timestamp: 1599093015000,
    type: "TEXT",
    data: {
      text: "Hello World"
    },
    messageId: "gBGHYoUiNWZwfwIJbtM1ryHfqTdp"
  }
}