Webhooks

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 SENTDELIVERED 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/Broadcast
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)


meta


PropertyTypeDescription
agentUserIdStringID of the user who sent the message.
sourceObjectThe information of the source integration; identical to apiSource
apiSourceObjectThe information of the source integration; to be deprecated soon


_source_


PropertyTypeDescription
integrationIdStringType of source integration
buildNumberVersion of the integration
appIntegrationStringID 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 CreateMember Subscription Status UpdateMember Livechat Status UpdateMember Meta UpdateMember 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_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

PropertyTypeDescription
eventTypeStringBATCH_MEMBER_UPDATE
functionNameStringThe batch update function, including OPEN_API_BATCH_CREATE_CHATOPEN_API_UPDATE_MEMBERSOPEN_API_BATCH_UPDATE_MEMBERSNORMAL_UPDATE_MEMBERSBATCH_ADD_TAGSBATCH_DELETE_TAGSBATCH_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.