Go to Snaps

Webhooks

Suggest Edits

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

What’s Next