Blog
These docs are for v1.0. Click to read the latest docs for v2.0.

Webhooks

Suggest Edits

Overview

Netcore has launched a Webhook feature in existing Smartech system which will act as a catalyst in the world of web marketing. Now, what web hook is all about? Web hook is nothing but a HTTP call back API, use to pass real time information to external system on a specific event set.

How does it Work:
As stated above, that web hook is nothing but a HTTP Callback. User will provide with an endpoint URL at the time of web hook creation which will be configured to receive the data. This URL (should be public) is known as Webhook Endpoint.
The callback will be triggered whenever a specified event will occur in a journey i.e. events for which “Send Webhook” is selected to notify or send info to an external system. The data or information that will be passed during the callback, will be mostly in the form of JSON format.

651

When you can setup Webhook:

  1. When user performed an action
    Example: User launched the app or User does add to cart.
  2. When user performed multiple actions
    Example: User launched the app and viewed a notification or User has open an email and click on the specific link.
  3. When user performed an action, but does not perform another action within a certain time
    Example: User click on specific link in Email and visited website, but does not buy product.
  4. When user performed an action, filtered by their demographic attributes
    Example: User purchased an item and lives in Canada

Few Use Cases:

  • Insurance
    Call Center should be able to call Higher (Hot) leads on priority.
  • Travel
    User looks up an international flight in business class, but doesn't book the flight within 30 minutes. Trigger a process in your call center to contact the user to complete the booking.
  • E-Commerce
    User abandons their cart during a high-value transaction. Trigger a call center process to contact the user to solve any issues and complete the purchase.

Channels With Corresponding Activities being Tracked by Webhook

ChannelActivity Tracked
EmailOpen
Click
Bounce
SMSDelivered
Click
BPNView
Click
APNView
Click

How to configure webhook in Smartech?

480

📘

Webhook supports 'HTTP 200' status URL only

Webhook Setup Steps:
1.Go to Assets -> Webhook -> Add webhook
2.Add the webhook url(Prereqisite for Webhook Setup)
3.Add webhook label
4.Click on 'test' to validate, if the test returns a 'HTTP 200' status the Webhook is operational and can be used on the panel.
5. Click Save

👍

Webhook Important Points

  • Make sure when you test the webhook URL you receive the 'HTTP 200' status
    • Make sure it has been running for 24 hours
    • The webhook call will be in async mode.

Authentication
Additionally, basic authentication consisting username & password is also available.(API or token based authentication will not work)

❗️

IP Whitelisting

User will have to white-list the Smartech IP addresses on their firewall to accept webhook requests

Best Practices:

  • To make sure that you are receiving data in the required format, please make sure that you have a dumper i.e a small script which will receive the data from the webhook call and log it for you, so that you can validate what you have received.
  • It also recommended to build a queuing system, since webhook will share the data continuously in batches and if your script gets busy in processing the received data then it would give 500 error on next batch and smartech will disable the webhook,

How to add webhook in journey?

Webhook as action type is available under 'Perform Action' in journeys.

Webhook (i.e. callback API) will use HTTP protocol and POST method to send the data.
Please see sample below for the reference for Channel Activity(the sample includes the cURL call, the data received in URLEncoded format and the data in json format).

📘

Point to Remember

  • Webhook (i.e. callback API) will use HTTP protocol and POST method to send the data.
  • CONTENT_TYPE for the call will be application/x-www-form-urlencoded
  • The webhook sends data in URL encoded format,where the key is data and the value is the actual JSON. 
curl -X POST \
  https://<webhookURL>.com/api/v2/message/ \  //Enter the webhook URL defined on the panel
  -H 'Authorization: Basic AUTHKEY' \	//Enter authentication key after BASIC
  -H 'Content-Type: application/x-www-form-urlencoded'

data="%7B%22panelname%22%3A%5B%7B%22webhook_name%22%3A%22SMS_CLICK%22%2C%22event_params%22%3A%7B%22foreignkey%22%3A%229999999997%22%2C%22linkid%22%3A-1%7D%2C%22custom_params%22%3A%7B%22automationid%22%3A%22169%22%2C%22link%22%3A%22http%3A%2F%2Fwww.some_link.com%22%2C%22channel%22%3A%22sms%22%2C%22leadscore%22%3A%22s2%22%7D%2C%22att_params%22%3A%7B%22MBR_DOBIRTH%22%3A%2223-12-88%22%2C%22AGE_BUCKET_APR17…"

data="%7B%22panelname%22%3A%5B%7B%22webhook_name%22%3A%22Email_CLICK%22%2C%22event_params%22%3A%7B%22foreignkey%22%3A%229999999997%22%2C%22linkid%22%3A-1%7D%2C%22custom_params%22%3A%7B%22automationid%22%3A%22169%22%2C%22link%22%3A%22http%3A%2F%2Fwww.some_link.com%22%2C%22channel%22%3A%22email%22%2C%22leadscore%22%3A%22s2%22%7D%2C%22att_params%22%3A%7B%22MBR_DOBIRTH%22%3A%2223-12-88%22%2C%22AGE_BUCKET_APR17…"

data="%7B%22panelname%22%3A%5B%7B%22webhook_name%22%3A%22APN_CLICK%22%2C%22event_params%22%3A%7B%22foreignkey%22%3A%229999999997%22%2C%22linkid%22%3A-1%7D%2C%22custom_params%22%3A%7B%22automationid%22%3A%22169%22%2C%22link%22%3A%22http%3A%2F%2Fwww.some_link.com%22%2C%22channel%22%3A%22apn%22%2C%22leadscore%22%3A%22s2%22%7D%2C%22att_params%22%3A%7B%22MBR_DOBIRTH%22%3A%2223-12-88%22%2C%22AGE_BUCKET_APR17…"

data="%7B%22panelname%22%3A%5B%7B%22webhook_name%22%3A%22BPN_CLICK%22%2C%22event_params%22%3A%7B%22foreignkey%22%3A%229999999997%22%2C%22linkid%22%3A-1%7D%2C%22custom_params%22%3A%7B%22automationid%22%3A%22169%22%2C%22link%22%3A%22http%3A%2F%2Fwww.some_link.com%22%2C%22channel%22%3A%22bpn%22%2C%22leadscore%22%3A%22s2%22%7D%2C%22att_params%22%3A%7B%22MBR_DOBIRTH%22%3A%2223-12-88%22%2C%22AGE_BUCKET_APR17…"

data = {
  {
  	"<panelname>": [                 //<panelname> is the name of the smartech panel 
    	{
      	"webhook_name": "SMS_CLICK", // in this case the webhook is genrated for SMS 	Click
      	"event_params": {
        	"foreignkey": "9999999997", // this is primary key from the panel.
        	"linkid": -1
      	},
      	"custom_params": {
        	"automationid": "169",
        	"link": "http://www.some_link.com",
        	"channel": "sms", // name of channel
        	"leadscore": "s2"
      	},
      	"att_params": { // this contain all attributes selected w.r.t. Smartech.
        	"MBR_DOBIRTH": "23-12-88",
        	"AGE_BUCKET_APR17": "25 To <30_Yr",
        	"MARIAL_STATUS": "S",
        	"CAMPAINGENAME": "CP Oct",
      	}
    	},
  	]
	}
}

data = {
  {
  	"<panelname>": [                 //<panelname> is the name of the smartech panel 
    	{
      	"webhook_name": "EMAIL_CLICK", // in this case the webhook is genrated for E-Mail Click
      	"event_params": {
        	"foreignkey": "9999999997", // this is primary key from the panel.
        	"linkid": -1
      	},
      	"custom_params": {
        	"automationid": "169",
        	"link": "http://www.some_link.com",
        	"channel": "email", // name of channel
        	"leadscore": "s2"
      	},
      	"att_params": { // this contain all attributes selected w.r.t. Smartech.
        	"MBR_DOBIRTH": "23-12-88",
        	"AGE_BUCKET_APR17": "25 To <30_Yr",
        	"MARIAL_STATUS": "S",
        	"CAMPAINGENAME": "CP Oct",
      	}
    	},
  	]
	}
}

data = {
  {
  	"<panelname>": [                 //<panelname> is the name of the smartech panel 
    	{
      	"webhook_name": "APN_CLICK", // in this case the webhook is genrated for E-Mail Click
      	"event_params": {
        	"foreignkey": "9999999997", // this is primary key from the panel.
        	"linkid": -1
      	},
      	"custom_params": {						
        	"automationid": "169",
        	"link": "http://www.some_link.com",
        	"channel": "APN", // name of channel
        	"leadscore": "s2"
      	},
      	"att_params": { // this contain all attributes selected w.r.t. Smartech.
        	"MBR_DOBIRTH": "23-12-88",
        	"AGE_BUCKET_APR17": "25 To <30_Yr",
        	"MARIAL_STATUS": "S",
        	"CAMPAINGENAME": "CP Oct",
      	}
    	},
  	]
	}
}

data = {
  {
  	"<panelname>": [                 //<panelname> is the name of the smartech panel 
    	{
      	"webhook_name": "BPN_CLICK", // in this case the webhook is genrated for E-Mail Click
      	"event_params": {
        	"foreignkey": "9999999997", // this is primary key from the panel.
        	"linkid": -1
      	},
      	"custom_params": {
        	"automationid": "169",
        	"link": "http://www.some_link.com",
        	"channel": "bpn", // name of channel
        	"leadscore": "s2"
      	},
      	"att_params": { // this contain all attributes selected w.r.t. Smartech.
        	"MBR_DOBIRTH": "23-12-88",
        	"AGE_BUCKET_APR17": "25 To <30_Yr",
        	"MARIAL_STATUS": "S",
        	"CAMPAINGENAME": "CP Oct",
      	}
    	},
  	]
	}
}

Webhook can also be sent for web activity. Say customer has done an activity as "Product Search"
In that case the the curl call and the data returned will be as shown below - 

curl -X POST \
  https://<webhookURL>.com/api/v2/message/ \  //Enter the webhook URL defined on the panel
  -H 'Authorization: Basic AUTHKEY' \			//Enter authentication key after BASIC
  -H 'Content-Type: application/x-www-form-urlencoded '

data="%7B%22%3Cpanel_name%3E%22%3A%5B%7B%22channel%22%3A%22custom_activity%22%2C%22custom_params%22%3A%7B%7D%2C%22att_params%22%3A%7B%22CITY%22%3A%22Thane%26Kalyan%22%2C%22STATE%22%3A%22Maharashtra11%22%7D%2C%22msgid%22%3A%22103%22%2C%22webhook_name%22%3A%22Test%20Webhook%20URL%20for%20Automation%22%2C%22payload_params%22%3A%7B%22items%22%3A%5B%7B%22dateofpurchase_sm%22%3A%222018-12-06%2017%3A11%3A30%22%2C%22category_s%22%3A%22lifestyle%22%2C%22prqt_s%22%3A1%2C%22prid_s%22%3A157%2C%22name_s%22%3A%22sarvesh12345%22%2C%22bydemand_s%22%3A%22sarvesh%22%2C%22price_s%22%3A9990.91%7D%2C%7B%22dateofpurchase_sm%22%3A%222018-12-06%2017%3A11%3A30%22%2C%22category_s%22%3A%22lifestyle%22%2C%22prqt_s%22%3A2%2C%22prid_s%22%3A157%2C%22name_s%22%3A%22sarvesh%22%2C%22bydemand_s%22%3A%22sarvesh%22%2C%22price_s%22%3A9990.91%7D%5D%7D%2C%22event_params%22%3A%7B%22activity_source%22%3A%22web%22%2C%22ts%22%3A181212120708%2C%22activity_id%22%3A103%2C%22foreignkey%22%3A%22%3Cforeignkey%3E%22%2C%22identity%22%3A%22%3Cidentity%3E%22%2C%22asset_name%22%3A%22%3Cname_of_asset_from_smartech%3E%22%2C%22asset_id%22%3A%22b001207f68c6e40519b5b2c7fb055930%22%2C%22guid%22%3A%222a867f6d-cb7f-4fb7-8da4-02a5d5dd1bd8%22%7D%2C%22journey_name%22%3A%22act%20on%20webhook%20trigger%20test1%22%7D%5D%7D%3Cdiv%3E"

data = {
  	{
  	"<panel_name>": [
    	{
      	"channel": "custom_activity",
      	"custom_params": {
          // custom param will be added here. From Journey you can select custome paramater which you want to pass.
      	},
      	"att_params": { // attribute will be added here with key:value combination
        	"CITY": "Thane&Kalyan",
        	"STATE": "Maharashtra11"
      	},
      	"msgid": "103",
      	"webhook_name": "Test Webhook URL for Automation",
      	"payload_params": { // these are the payload parameter which you are passing with activity.
        	"items": [
          	{
            	"dateofpurchase_sm": "2018-12-06 17:11:30",
            	"category_s": "lifestyle",
            	"prqt_s": 1,
            	"prid_s": 157,
            	"name_s": "sarvesh12345",
            	"bydemand_s": "sarvesh",
            	"price_s": 9990.91
          	},
          	{
            	"dateofpurchase_sm": "2018-12-06 17:11:30",
            	"category_s": "lifestyle",
            	"prqt_s": 2,
            	"prid_s": 157,
            	"name_s": "sarvesh",
            	"bydemand_s": "sarvesh",
            	"price_s": 9990.91
          	}
        	]
      	},
      	"event_params": {
        	"activity_source": "web",
        	"ts": 181212120708,
        	"activity_id": 103,
        	"foreignkey": "<foreignkey>",
        	"identity": "<identity>",
        	"asset_name": "<name_of_asset_from_smartech>", // name of asset while creating webhook
        	"asset_id": "b001207f68c6e40519b5b2c7fb055930", // id os asset which creating webhook
        	"guid": "2a867f6d-cb7f-4fb7-8da4-02a5d5dd1bd8"
      	},
      	"journey_name": "act on webhook trigger test1" // name of journey.
    	}
  	]
	}
}

Webhook Failure Alert

Webhooks can fail due to multiple reasons, when this happens this can lead to loss of information on the client side.
To solve this we have the webhook failure alert feature. A user can set an alert to be sent to the respective stakeholder's email IDs whenever a webhook fails.

Steps to setup Webhook Failure Alerts:

  • Navigate to the webhook page from the assets section.
  • Click on the edit option under any webhook set, this opens the webhook setup where you can find a checkbox for webhook alerts .
  • Click on it, it expands to provide options to set up the frequency of alerts and the emails of the stakeholder to whom the emails are to be sent.
  • Now, whenever that specific webhook fails the user will get an email alert for the same.
511

Updated almost 4 years ago