Overview

Netcore has launched a Webhook feature in existing CEE 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.

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
BPNDelivered
Click
APNDelivered
Click

How to configure webhook in CEE?

Webhook Setup Steps:
1.Go to Assets -> Webhook -> Add webhook
2.Add the webhook URL. We support both HTTP and HTTPS URLS. (Prerequisite 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.

  1. 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 CEE 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 CEE will disable the webhook,

How to add webhook in journey?

Steps to add Webhook in Journey:

  1. Start with a trigger .i.e. activity/segment/list
  2. Set up a action node such as Email, SMS, App push and Web push
  3. Add wait for event from flow control. Select activity status as open/click for Email and delivered/click for SMS, App push and Web push
  4. Select 'wait until period' to capture activity status of Email/SMS/App push/Web push. Please note: this node is mandatory to add a webhook
  5. From Action add webhook node to canvas and link to 'wait for event' node
  6. Select webhook that is configured in the asset section. Channel and Activity will be fetched from wait for event node.
  7. You can also choose from a list of parameters and attributes that can be passed along with webhook operation.
  8. The activity status of this webhook will be passed for the journey which is in running status.

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%22qa_manual1%22%3A%5B%7B%22channel%22%3A%22sms%22%2C%22event%22%3A%22delivered%22%2C%22custom_params%22%3A%7B%22Action%22%3A%22SMS%20Deliver%22%7D%2C%22att_params%22%3A%7B%22LASTNAME%22%3A%22%22%2C%22FIRSTNAME%22%3A%22%22%2C%22MOBILE%22%3A%229999999999%22%2C%22EMAIL%22%3A%22abcd%40gmail.com%22%7D%2C%22msgid%22%3A%221318%22%2C%22webhook_name%22%3A%22testqa112%22%2C%22event_params%22%3A%7B%22foreignkey%22%3A%22abcd%40gmail.com%22%2C%22timestamp%22%3A%222022-12-01T18%3A12%3A46%22%2C%22ts%22%3A221201181246%2C%22name%22%3A%22WebHook%20Test_SMS%22%2C%22mobile%22%3A%228281904975%22%7D%2C%22journey_name%22%3A%22Webhook%20Journey_SMS%22%7D%2C%7B%22channel%22%3A%22email%22%2C%22event%22%3A%22open%22%2C%22custom_params%22%3A%7B%22Action%22%3A%22Email%20Open%22%7D%2C%22att_params%22%3A%7B%22LASTNAME%22%3A%22Thomas%22%2C%22FIRSTNAME%22%3A%22RMT%22%2C%22MOBILE%22%3A%221234567890%22%2C%22EMAIL%22%3A%22abcde%40gmail.com%22%7D%2C%22msgid%22%3A%224930%22%2C%22webhook_name%22%3A%22testqa112%22%2C%22event_params%22%3A%7B%22ip_addr%22%3A%2266.249.84.250%22%2C%22foreignkey%22%3A%22abcde%40gmail.com%22%2C%22timestamp%22%3A%222022-12-01T18%3A12%3A54%22%2C%22ts%22%3A221201181254%2C%22user_agent%22%3A%22Mozilla%2F5.0%20%28Windows%20NT%205.1%3B%20rv%3A11.0%29%20Gecko%20Firefox%2F11.0%20%28via%20ggpht.com%20GoogleImageProxy%29%22%2C%22name%22%3Anull%2C%22mobile%22%3A%221234567890%22%7D%2C%22journey_name%22%3A%22Webhook%20Journey_Email%22%7D%5D%7D"
data="%7B%22pod2_email_rashmi%22%3A%5B%7B%22webhook_name%22%3A%22Email%20Open%20Webhook%22%2C%22msgid%22%3A%22546%22%2C%22channel%22%3A%22email%22%2C%22event_params%22%3A%7B%22ip_addr%22%3A%22106.51.148.72%22%2C%22subject%22%3A%22email%20broadcast%20to%20check%20webhook%20in%20broadcast%20111%22%2C%22ts%22%3A221202154805%2C%22fromfield%22%3A%22sa%20%3Csa%40m3m.in%3E%22%2C%22camp_name%22%3A%22email%20broadcast%20to%20check%20webhook%20in%20broadcast%20111%22%2C%22useragent%22%3A%22Mozilla%2F5.0%20%28X11%3B%20Linux%20x86_64%3B%20rv%3A45.0%29%20Gecko%2F20100101%20Thunderbird%2F45.3.0%20Lightning%2F4.7.4%22%2C%22tags%22%3A%22%22%2C%22email%22%3A%22test%40gmail.com%22%2C%22timestamp%22%3A%222022-12-02T15%3A48%3A05%22%2C%22foreignkey%22%3A%22test%40gmail.com%22%7D%2C%22event%22%3A%22open%22%2C%22custom_params%22%3A%7B%22smartech_panel%22%3A%2222428%22%2C%22userid%22%3A%2222428-546-40823%22%7D%2C%22udt_params%22%3A%7B%22attr1%22%3A%22value1%22%2C%22attr2%22%3A%22value2%22%7D%7D%5D%7D"
data="%7B%22pod2_email_rashmi%22%3A%5B%7B%22channel%22%3A%22apn%22%2C%22event%22%3A%22delivered%22%2C%22custom_params%22%3A%7B%22Action%22%3A%22APN%20Deliver%22%7D%2C%22att_params%22%3A%7B%22CITY%22%3A%22Webhook%22%2C%22MOBILE%22%3A%229999999999%22%2C%22EMAIL%22%3A%22abcd%40gmail.com%22%7D%2C%22msgid%22%3A%22291%22%2C%22webhook_name%22%3A%22tushar_test%22%2C%22event_params%22%3A%7B%22ip_addr%22%3A%2214.142.143.138%22%2C%22ts%22%3A221125154047%2C%22user_agent%22%3A%22Mozilla%2F5.0%20%28X11%3B%20Linux%20x86_64%29%20AppleWebKit%2F537.36%20%28KHTML%2C%20like%20Gecko%29%20Chrome%2F107.0.0.0%20Safari%2F537.36%22%2C%22name%22%3Anull%2C%22token_id%22%3Anull%2C%22timestamp%22%3A%222022-11-25T15%3A40%3A47%22%2C%22foreignkey%22%3A%22abcd%40gmail.com%22%2C%22token%22%3A%5B%22fYOsTM2fTKJT7u1Ytyo6L2%3AAPA91bGMraEGETT2OHnywGCIZT9zvvLUD2Jf354Z3lXHFrJZa6xBH1aHPWQYlohYOA7Mt3u27unofPNkqepcTIjIHn4mrUITblIAbF8H3Fe2gbFM8P_5PWH7rjEbsJaXKZXK40W15b9r%22%5D%7D%2C%22journey_name%22%3A%22APN_channel_WBh%22%7D%5D%7D"
data="%7B%22pod2_email_rashmi%22%3A%5B%7B%22channel%22%3A%22bpn%22%2C%22event%22%3A%22delivered%22%2C%22custom_params%22%3A%7B%22Action%22%3A%22BPN%20Deliver%22%7D%2C%22att_params%22%3A%7B%22CITY%22%3A%22Webhook%22%2C%22MOBILE%22%3A%229999999999%22%2C%22EMAIL%22%3A%22abcde%40gmail.com%22%7D%2C%22msgid%22%3A%22291%22%2C%22webhook_name%22%3A%22tushar_test%22%2C%22event_params%22%3A%7B%22ip_addr%22%3A%2214.142.143.138%22%2C%22ts%22%3A221125154047%2C%22user_agent%22%3A%22Mozilla%2F5.0%20%28X11%3B%20Linux%20x86_64%29%20AppleWebKit%2F537.36%20%28KHTML%2C%20like%20Gecko%29%20Chrome%2F107.0.0.0%20Safari%2F537.36%22%2C%22name%22%3Anull%2C%22token_id%22%3Anull%2C%22timestamp%22%3A%222022-11-25T15%3A40%3A47%22%2C%22foreignkey%22%3A%22abcde%40gmail.com%22%2C%22token%22%3A%5B%22fYOsTM2fTKJT7u1Ytyo6L2%3AAPA91bGMraEGETT2OHnywGCIZT9zvvLUD2Jf354Z3lXHFrJZa6xBH1aHPWQYlohYOA7Mt3u27unofPNkqepcTIjIHn4mrUITblIAbF8H3Fe2gbFM8P_5PWH7rjEbsJaXKZXK40W15b9r%22%5D%7D%2C%22journey_name%22%3A%22BPN_channel_WBh%22%7D%5D%7D"
data = {
  "qa_manual1": [
    {
      "channel": "sms",
      "event": "delivered",
      "custom_params": {
        "Action": "SMS Deliver"
      },
      "att_params": {
        "LASTNAME": "",
        "FIRSTNAME": "",
        "MOBILE": "9999999999",
        "EMAIL": "[email protected]"
      },
      "msgid": "1318",
      "webhook_name": "testqa112",
      "event_params": {
        "foreignkey": "[email protected]",
        "timestamp": "2022-12-01T18:12:46",
        "ts": 221201181246,
        "name": "WebHook Test_SMS",
        "mobile": "8281904975"
      },
      "journey_name": "Webhook Journey_SMS"
    },
    {
      "channel": "email",
      "event": "open",
      "custom_params": {
        "Action": "Email Open"
      },
      "att_params": {
        "LASTNAME": "Thomas",
        "FIRSTNAME": "RMT",
        "MOBILE": "1234567890",
        "EMAIL": "[email protected]"
      },
      "msgid": "4930",
      "webhook_name": "testqa112",
      "event_params": {
        "ip_addr": "66.249.84.250",
        "foreignkey": "[email protected]",
        "timestamp": "2022-12-01T18:12:54",
        "ts": 221201181254,
        "user_agent": "Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)",
        "name": null,
        "mobile": "1234567890"
      },
      "journey_name": "Webhook Journey_Email"
    }
  ]
}
data = {
  "pod2_email_rashmi": [
    {
  "webhook_name": "Email Open Webhook",
  "msgid": "546",
  "channel": "email",
  "event_params": {
    "ip_addr": "106.51.148.72",
    "subject": "email broadcast to check webhook in broadcast 111",
    "ts": 221202154805,
    "fromfield": "sa <[email protected]>",
    "camp_name": "email broadcast to check webhook in broadcast 111",
    "useragent": "Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.3.0 Lightning/4.7.4",
    "tags": "",
    "email": "[email protected]",
    "timestamp": "2022-12-02T15:48:05",
    "foreignkey": "[email protected]"
  },
  "event": "open",
  "custom_params": {
    "smartech_panel": "22428",
    "userid": "22428-546-40823"
  },
"udt_params" : { 
        "attr1" : "value1",
        "attr2" :"value2"
    	}
    }
  ]
}
data = {
  "pod2_email_rashmi": [
    {
      "channel": "apn",
      "event": "delivered",
      "custom_params": {
        "Action": "APN Deliver"
      },
      "att_params": {
        "CITY": "Webhook",
        "MOBILE": "9999999999",
        "EMAIL": "[email protected]"
      },
      "msgid": "291",
      "webhook_name": "tushar_test",
      "event_params": {
        "ip_addr": "14.142.143.138",
        "ts": 221125154047,
        "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/107.0.0.0 Safari/537.36",
        "name": null,
        "token_id": null,
        "timestamp": "2022-11-25T15:40:47",
        "foreignkey": "[email protected]",
        "token": [
          "fYOsTM2fTKJT7u1Ytyo6L2:APA91bGMraEGETT2OHnywGCIZT9zvvLUD2Jf354Z3lXHFrJZa6xBH1aHPWQYlohYOA7Mt3u27unofPNkqepcTIjIHn4mrUITblIAbF8H3Fe2gbFM8P_5PWH7rjEbsJaXKZXK40W15b9r"
        ]
      },
      "journey_name": "APN_channel_WBh"
    }
  ]
}
data = {
  "pod2_email_rashmi": [
    {
      "channel": "bpn",
      "event": "delivered",
      "custom_params": {
        "Action": "BPN Deliver"
      },
      "att_params": {
        "CITY": "Webhook",
        "MOBILE": "9999999999",
        "EMAIL": "[email protected]"
      },
      "msgid": "291",
      "webhook_name": "tushar_test",
      "event_params": {
        "ip_addr": "14.142.143.138",
        "ts": 221125154047,
        "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/107.0.0.0 Safari/537.36",
        "name": null,
        "token_id": null,
        "timestamp": "2022-11-25T15:40:47",
        "foreignkey": "[email protected]",
        "token": [
          "fYOsTM2fTKJT7u1Ytyo6L2:APA91bGMraEGETT2OHnywGCIZT9zvvLUD2Jf354Z3lXHFrJZa6xBH1aHPWQYlohYOA7Mt3u27unofPNkqepcTIjIHn4mrUITblIAbF8H3Fe2gbFM8P_5PWH7rjEbsJaXKZXK40W15b9r"
        ]
      },
      "journey_name": "BPN_channel_WBh"
    }
  ]
}

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%3A221202154805%2C%22activity_id%22%3A103%2C%22timestamp%22%3A%222022-12-02T15%3A48%3A05%22%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"
{
  "<panel_name>": [
    {
      "channel": "custom_activity",
      "custom_params": {},
      "att_params": {
        "CITY": "Thane&Kalyan",
        "STATE": "Maharashtra11"
      },
      "msgid": "103",
      "webhook_name": "Test Webhook URL for Automation",
      "payload_params": {
        "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": 221202154805,
        "activity_id": 103,
        "timestamp": "2022-12-02T15:48:05",
        "foreignkey": "<foreignkey>",
        "identity": "<identity>",
        "asset_name": "<name_of_asset_from_smartech>",
        "asset_id": "b001207f68c6e40519b5b2c7fb055930",
        "guid": "2a867f6d-cb7f-4fb7-8da4-02a5d5dd1bd8"
      },
      "journey_name": "act on webhook trigger test1"
    }
  ]
}

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.