Webhooks

Validation

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

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

Inbound Messages

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

Sample from WhatsApp

Text message:

{
  "from": "85260903521",
  "to": "85268227287",
  "timestamp": "1599536864",
  "type": "TEXT",
  "data": {
    "text": "Hello"
  }
  "member": "memberId",
  "channel": "channeId",
  "app": "appId",
  "memberExtraData": {
    "field": "Test Metadata",
    "path": "gender"
  }
}

Video message:

{
  "from": "85260903521",
  "to": "85268227287",
  "timestamp": "1599536864",
  "type": "MISC",
  "data": {
    "attachments": [{
      "type": "VIDEO",
      "waMediaId": "e8a85916-2386-49dc-8f05-1cd0527bfb68",
    }],
  }
  "member": "memberId",
  "channel": "channeId",
  "app": "appId",
  "memberExtraData": {
    "field": "Test Metadata",
    "path": "gender"
  }
}

Message Status Update

Apart from the message event, you can also receive message status update by subscribing to the inbound messages, such as the SENT, DELIVERED and READ events from WhatsApp.

Sample from WhatsApp

When the message status becomes READ:

{
  "to": "85268227287",
  "timestamp": 1701914905000,
  "messageId": "wamid.ABcLODUyNTQwNjM1OTgVAgARGBJCRDc4MkU4QTUzREFCMkU3REEA",
  "from": "85254063598",
  "data": {
    "messageId": "wamid.ABcLODUyNTQwNjM1OTgVAgARGBJCRDc4MkU4QTUzREFCMkU3REEA"
  },
  "type": "READ",
  "eventType": "INBOUND",
  "member": "MEMBER_ID",
  "channel": "CHANNEL_ID",
  "app": "APP_ID"
}

Outbound Messages

`body`

Property	Type	Description
type	String	Can be either `BOT`or `MANUAL`. Indicating whether the outbound message is from the chatbot or from API/Broadcast
member	String	ID of the member
channel	String	ID of the channel
app	String	ID of the app
meta	Object	`apiSource` that includes information of the source integration
memberExtraData	Object	Extra member data and an valid member path
customHeadersData	Object	Custom header key and custom header value
messageEvent	Object	messageEvent object containing the normalised message

`messageEvent`

Property	Type	Description
from	String	ID of the sender
to	String	ID of the recipient
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 exist)

`meta`

Property	Type	Description
agentUserId	String	ID of the user who sent the message.
source	Object	The information of the source integration; identical to `apiSource`
apiSource	Object	The information of the source integration; to be deprecated soon

`_source_`

Property	Type	Description
integrationId	String	Type of source integration
build	Number	Version of the integration
appIntegration	String	ID of the integration

Sample event

{
  "type": "MANUAL",
  "app": "APP_ID",
  "channel": "CHANNEL_ID",
  "member": "MEMBER_ID",
  "eventType": "API_OUTBOUND",
  "meta": {
    "agentUserId": "59cb495865243d002c6fc1f5",
    "apiSource": {
      "integrationId": "inbox",
      "build": 1,
      "appIntegration": "6420ffb53e65b445d4657ee1"
    },
    "__source__": {
      "integrationId": "inbox",
      "build": 1,
      "appIntegration": "6420ffb53e65b445d4657ee1"
    }
  },
  "messageEvent": {
    "from": "14132521446",
    "to": "85260903521",
    "data": {
      "text": "hihi"
    },
    "type": "TEXT",
    "timestamp": 1712807869354,
    "messageId": "wamid.HBgLODUyNjA5MDM1MjEVAgARGBJFMkI5MkQwODQ1NDc3Q0UwM0QA"
  }, 
}

NOTE

The agentUserId in the outbound message can be used to obtain the team member information with the Open API query:

query getTeamMembersUserIdAndEmail
{
  apiViewer {
    app {
      teamMembers {
        user {
          _id
          email {
            email
          }
        }
      }
    }
  }
}

Bot Outbound Messages

The chatbot response messages will be sent to your designated webhook.

API Outbound Messages

The messages sent via SendResponse API will be sent to your designated webhook.

Broadcast Outbound Messages

The messages sent via the Broadcast will be sent to to your designated webhook.

Member Update Events

By subscribing to these events, you would receive the events whenever there is status change on a member of this channel.

The Member Update Events include: Member Create, Member Subscription Status Update, Member Livechat Status Update, Member Meta Update, Member Temp Data Update and Member Tags Update.

`body`

Property	Type	Description
eventType	String	`MEMBER_UPDATE`
functionName	String	`NORMAL_UPDATE_MEMBER`: update the member manually in members page; `BOT_UPDATE_MEMBER`: update the member with bot
member	String	ID of the member
channel	String	ID of the channel
app	String	ID of the app
before	Object	Status of the member before the change
after	Object	Status of the member after the change

Sample Event

{
  "eventType": "MEMBER_UPDATE",
  "functionName": "NORMAL_UPDATE_MEMBER",
  "member": "memberId",
  "channel": "channelId",
  "app": "appId",
  "before": {
    "liveChat": false,
    "tempData": {
      "faqAns": [],
      "listLength": 5
    },
    "tags": [
      "test_broadcast"
    ]
  },
  "after": {
    "liveChat": true,
    "tempData": {
      "faqAns": [],
      "listLength": 1
    },
    "tags": [
      "test_broadcast",
      "testing_tag_2"
    ]
  }
}

Batch Member Updates

When multiple members are updated in batch at the a time, you would receive the event type BATCH_MEMBER_UPDATE.

`body`

Property	Type	Description
eventType	String	`BATCH_MEMBER_UPDATE`
functionName	String	The batch update function, including `OPEN_API_BATCH_CREATE_CHAT`, `OPEN_API_UPDATE_MEMBERS`, `OPEN_API_BATCH_UPDATE_MEMBERS`, `NORMAL_UPDATE_MEMBERS`, `BATCH_ADD_TAGS`, `BATCH_DELETE_TAGS`, `BATCH_REPLACE_TAGS`
members	Array	Array of member IDs
channel	String	ID of the channel
app	String	ID of the app
update	Object	Details of the member update

Sample Event

{
  "eventType": "BATCH_MEMBER_UPDATE",
  "functionName": "BATCH_ADD_TAGS",
  "members": [
    "memberId_1",
    "memberId_2",
    "memberId_3",
    "memberId_4",
    "memberId_5",
    "memberId_6"
  ],
  "channel": "channelId",
  "app": "appId",
  "update": {
    "$addToSet": {
      "tags": {
        "$each": [
          "testing_tag_1"
        ]
      }
    }
  }
}

Node Triggered Events

By subscribing to this, you would receive events whenever a node is triggered in this channel.

`body`

Property	Type	Description
eventType	String	`NODE_TRIGGER`
app	String	ID of the app
channel	String	ID of the channel
member	String	ID of the member
timestamp	String	Time when the node is triggered
node	String	nodeId
compositeId	String	Unique ID of a node
tree	String	ID of the tree
messageEvent	Object	messageEvent object containing the normalised message

Sample Event

{
  "app": "appId",
  "channel": "channelId",
  "member": "memberId",
  "timestamp": 1680605255829,
  "node": "nodeId",
  "compositeId": null,
  "tree": "treeId",
  "eventType": "NODE_TRIGGER"
  "messageEvent": {
    "to": "123461662163",
    "timestamp": 1680605248000,
    "messageId": "wamid.HLavODUyNTpRNjM1OTgVAgASGBYzRUabcjRDNTcxQjhPQ8E3MEI0MkFCAA==",
    "from": "85212345678",
    "type": "TEXT",
    "data": {
      "text": "Testing"
    }
  }
}

Manage Webhooks in the Channel

The new channel webhook system allows better control over the events received by your webhook. In the channel's "Environment" page, you can manage your webhooks subscribed to each environment of a channel.

NOTE

If you channel webhook system is still on the deprecating version, an upgrade reminder will be displayed whenever you enter the channel environment.

Create Webhooks

To add a webhook to your channel, select "+ Create a New Webhook".

Input the webhook URL, and select the events you want to subscribe to. Finally, click "Confirm" to confirm the webhook settings.

After closing the previous modal, please remember to "Save" and the environment settings again.

Edit Webhooks

To edit your webhook, click on "more" and select "Edit".

Remember to "Confirm" the changes made to the existing webhook.

Remove Webhooks

To edit your webhook, click on "more" and select "Remove".

The new channel webhook system also supports sending Member Metadata and Custom Headers. To apply them to your webhook, please select "Show Advanced Menu".

Then, you can see the Member Metadata and Custom Headers sections.

After filling in the all the required values, you can click on "Confirm" to confirm the settings.

Validation​

Inbound Messages​

Sample from WhatsApp​

Message Status Update​

Sample from WhatsApp​

Outbound Messages​

body​

messageEvent​

meta​

_source_​

Sample event​

NOTE

Bot Outbound Messages​

API Outbound Messages​

Broadcast Outbound Messages​

Member Update Events​

body​

Sample Event​

Batch Member Updates​

body​

Sample Event​

Node Triggered Events​

body​

Sample Event​

Manage Webhooks in the Channel​

NOTE

Create Webhooks​

Edit Webhooks​

Remove Webhooks​

Advanced Menu​

Validation

Inbound Messages

Sample from WhatsApp

Message Status Update

Sample from WhatsApp

Outbound Messages

`body`

`messageEvent`

`meta`

`_source_`

Sample event

Bot Outbound Messages

API Outbound Messages

Broadcast Outbound Messages

Member Update Events

`body`

Sample Event

Batch Member Updates

`body`

Sample Event

Node Triggered Events

`body`

Sample Event

Manage Webhooks in the Channel

Create Webhooks

Edit Webhooks

Remove Webhooks

Advanced Menu