Webhooks
When you created your application, you provided a webhook url where Snaps will post all relevant events that occur on subscribed channels. These webhook events allow you to monitor events across all subscribed channel activity including receiving control status updates with respect to an individual user's conversational channel experience.
Verifying Events
Events created through the Snaps Conversations API can be verified by calculating a digital signature. Each event includes a base64-encoded X-Snaps-Hmac-SHA256 header, which is generated using the app's shared secret along with the data sent in the request.
To verify that the request came from Snaps, compute the HMAC digest according to the following algorithm and compare it to the value in the X-Snaps-Hmac-SHA256 header. If they match, then you can be sure that the event was sent from Snaps.
const crypto = require('crypto');
const SNAPS_SHARED_SECRET = 'abcdefg';
const handler = (req, res) => {
const {
headers: {
'x-snaps-hmac-sha256': request_hash,
},
body,
} = req;
const hash = crypto.createHmac('sha256', SNAPS_SHARED_SECRET)
.update(JSON.stringify(body))
.digest('base64');
let isSigned = false;
try {
isSigned = crypto.timingSafeEqual(
Buffer.from(hash),
Buffer.from(request_hash)
);
}
catch (e) {
isSigned = false;
}
if (isSigned) {
console.log('request is signed by snaps');
}
else {
console.log('unverified request');
}
};
Event Types
There are 8 types of events that your webhook can receive. All webhook events will share the same base set of properties which can be found below as Standard Webhook Properties
. Below that, the contents and timing of individual webhook types is described.
Standard Event Properties
The following properties will be included with every event that your webhook receives.
{
"event_id": "",
"event_type": "",
"conversation_id": "",
"initiator": "",
"channel_id": "",
"channel_type": "",
"snaps_user_id": "",
"channel_user_ref": "",
"current_conversation_owner": "",
"timestamp": "",
"payload": {}
}
event_id
: The globally unique Snaps event ID.event_type
: One of [ 'message_send', 'message_delivery', 'link_click', 'add_to_cart', 'page_view', 'order_complete', 'custom', 'control_change', 'user_property_set' ]conversation_id
: The ID of the conversation within which the event occurred.channel_id
: The ID of the channel entity in the Snaps platform.channel_type
: One of['sms', 'web', 'messenger', 'twitter', 'viber', 'ios', 'android', 'email']
.snaps_user_id
: A unique user id assigned by Snaps in the format of a 24 character objectId hex string.channel_user_ref
: Channel type specific unique identifier such as a phone number for SMS.initiator
: One of['user', 'application']
. Describes who initiated the action which the event was created for.current_conversation_owner
: The application_id responsible for control the conversation flow.timestamp
: The milliseconds since epoch at which this event occurred.payload
: An object containing information specific to theevent_type
. The contents of this object are described at length below.
Message Send
The below section will describe the payload object of a message_send
webhook event. See above for the common fields associated with all webhook events. The message_send
event will be delivered to your webhook whenever a message is sent within a conversation. This includes messages sent by the user, the bot, or another application.
{
"messages": [
{
"text": "Thanks!"
}
]
}
message
: The message key will contain the full content of the message that was sent. For detail on what this object will look like for different message types, see the Sending Messages section.
User Property Set
The below section will describe the payload object of a user_property_set
webhook event. See above for the common fields associated with all webhook events.
{
"name": "favorite_color",
"value": "yellow"
}
name
: The name of the user property.value
: The value of the user property.
Link Click
The below section will describe the payload object of a link_click
webhook event. See above for the common fields associated with all webhook events.
{
"url": "https://example.com",
"query": {
"my_query_parameter": "its_value"
}
}
url
: The url of the link that the user clicked.query
: An object containing all of the query params that were present on the link when it was clicked.
Control Change
The below section will describe the payload object of a control_change
webhook event. See above for the common fields associated with all webhook events.
{
"action": "",
"from_application_id": "",
"to_application_id": ""
}
action
: One of['take', 'pass']
. Indicates whether the conversation was taken of passed by the calling application.from_application_id
: The ID of the application who had control of the conversation before the action was taken.to_application_id
: The ID of the application who had control of the conversation after the action was taken.
Add to Cart
The below section will describe the payload object of an add_to_cart
webhook event. See above for the common fields associated with all webhook events.
{
"url": "https://www.juul.com/shop/pods/mango-5-percent",
"item": "MANGO",
"price": "15.99"
}
url
: The url on which the event was recorded.item
: The title of the item which was added to the users cart.price
: The price of the item that was added to the users cart.
Page View
The below section will describe the payload object of an page_view
webhook event. See above for the common fields associated with all webhook events.
{
"url": "https://docs.snaps.io/docs/webhook-events"
}
url
: The url of the page the user viewed.
Order Complete
The below section will describe the payload object of a order_complete
webhook event. See above for the common fields associated with all webhook events.
{
url: '',
item: '',
price: '',
}
url
: The url of the page on which the event was generated.items
: An array of items that were purchased.total_price
: The total price of all items that were purchased.
Custom
The below section will describe the payload object of a custom
webhook event. See above for the common fields associated with all webhook events.
{
"event_name": "",
"data": {}
}
event_name
: The name this custom event was created with.data
: The data associated with this custom event.
Updated about 1 year ago