Skip to main content

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.

  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-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

PropertyTypeDescription
typeStringCan be either BOTor MANUAL. Indicating whether the outbound message is from the chatbot or from API/Push
memberStringID of the member
channelStringID of the channel
appStringID of the app
metaObjectapiSource that includes information of the source integration
memberExtraDataObjectExtra member data and an valid member path
customHeadersDataObjectCustom header key and custom header value
messageEventObjectmessageEvent object containing the normalised message

messageEvent

PropertyTypeDescription
fromStringID of the sender
toStringID of the recipient
timestampNumberUnix timestamp
typeStringMessage type
dataObjectMessage data for the corresponding message type
messageIdStringMessage ID from the external platform (this property might not exist)

apiSource

PropertyTypeDescription
integrationIdStringType of source integration
buildNumberVersion of the integration
appIntegrationID of the integration
NOTE

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

Sample event

{
"type": "MANUAL",
"app": "APP_ID",
"channel": "CHANNEL_ID",
"member": "MEMBER_ID",
"eventType": "API_OUTBOUND",
"meta": {
"apiSource": {
"integrationId": "inbox",
"build": 1,
"appIntegration": "12abcbe43b0109b31a206d49"
}
},
"messageEvent": {
"from": "104288815736706",
"to": "6520545274654915",
"data": {
"text": "hi"
},
"type": "TEXT",
"timestamp": 1700643519999,
"messageId": "m_xJ2e9ry7KOR-HFcKhOX5bfSy-IeC__I7KO6vfn-jTa-fptqhnReLzQYSdNFg-HcynlsYgAStH6i_J3u5aJQi-g"
}
}

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.

Push Outbound Messages

The messages sent via the Push Panel 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

PropertyTypeDescription
eventTypeStringMEMBER_UPDATE
functionNameStringNORMAL_UPDATE_MEMBER: update the member manually in members page;
BOT_UPDATE_MEMBER: update the member with bot
memberStringID of the member
channelStringID of the channel
appStringID of the app
beforeObjectStatus of the member before the change
afterObjectStatus 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_push"
]
},
"after": {
"liveChat": true,
"tempData": {
"faqAns": [],
"listLength": 1
},
"tags": [
"test_push",
"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

PropertyTypeDescription
eventTypeStringBATCH_MEMBER_UPDATE
functionNameStringThe 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
membersArrayArray of member IDs
channelStringID of the channel
appStringID of the app
updateObjectDetails 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

PropertyTypeDescription
eventTypeStringNODE_TRIGGER
appStringID of the app
channelStringID of the channel
memberStringID of the member
timestampStringTime when the node is triggered
nodeStringnodeId
compositeIdStringUnique ID of a node
treeStringID of the tree
messageEventObjectmessageEvent 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

  1. To add a webhook to your channel, select "+ Create a New Webhook".
  1. Input the webhook URL, and select the events you want to subscribe to. Finally, click "Confirm" to confirm the webhook settings.
  1. After closing the previous modal, please remember to "Save" and the environment settings again.

Edit Webhooks

  1. To edit your webhook, click on "more" and select "Edit".
  1. Remember to "Confirm" the changes made to the existing webhook.

Remove Webhooks

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

Advanced Menu

  1. The new channel webhook system also supports sending Member Metadata and Custom Headers. To apply them to your webhook, please select "Show Advanced Menu".
  1. Then, you can see the Member Metadata and Custom Headers sections.
  1. After filling in the all the required values, you can click on "Confirm" to confirm the settings.