WebEngage webhooks let you add an HTTP callback to the events happening in WebEngage. By configuring a webhook, WebEngage is triggered to call a script on your web-servers whenever a particular event, for which you want to get real-time data, occurs and use it for internal purposes. You can use webhooks to send information to systems such as Salesforce. You can also use webhooks to send information to your backend systems. For example, you might want to credit your customers' accounts with a promotion once they’ve performed a custom event a certain number of times.

Webhook requests

Webhook requests will be posted to a URL configured by you and in the format described below. Webhook request method will always be POST. There will be additional parameters that will be appended to the postURL.

Request headers

Name Description
x-request-id:{HEX_STRING} Used to identify webhook POST requests uniquely to achieve events idempotency. {HEX_STRING} will be replaced by a unique random hex string.

Request parameters

Name
Description

eventType

Event for which data is being sent

licenseCode

Your WebEngage account license code

secret

This secret key is to be used to identify the webhook POST requests from WebEngage. More about request verification below.

Request body

Request body will contain event specific data. The request body will vary based on the registered webhook.

Response

WebEngage will understand HTTP Status, of the response. Responses with HTTP Status 200 will be treated as successful posts, everything else will be logged as failed webhook posts.
See the section about error handling and retries below to understand what happens in case of failures.

Request verification

You will find Webhook Secret Key for your account in the Integrations > Webhooks section of WebEngage dashboard. This secret key is to be used to identify the Webhook POST requests from WebEngage to your servers. WebEngage appends a parameter named secret in the postURL. Value of this parameter is the MD5 Hex of the combination of your WebEngage license code and the Webhook Secret Key separated by :.

Error handling and retries

WebEngage keeps a log of recent webhook requests under History tab in the Integrations > Webhooks section of your dashboard. You can manage failed requests from here. You will be able to retry a particular failed webhook request by clicking the Resend link against that history item. Automatic retries are currently not supported.

Webhook configuration

You will be able to configure URLs for different events from the Integrations > Webhooks section of your WebEngage dashboard. Following are the webhooks you can configure.

Feedback Webhook

Triggers on feedback submission. To add a webhook specific to FEEDBACK_SUBMIT event, you need to configure this webhook by specifying the postURL and the response format (XML or JSON). Feedback data will be the same as that received from /feedback/<FeedbackId> API call.

Feedback Reply Webhook

Triggers when a reply is posted to an existing feedback thread. To add a webhook specific to FEEDBACK_REPLY_SUBMIT event, you need to configure this webhook by specifying the postURL and the response format (XML or JSON). Feedback reply data will be the same as that received from /feedback/<FeedbackId>/replies API call.

Survey Response Webhook

Triggers when survey response is submitted. To add a webhook specific to SURVEY_RESPONSE_SUBMIT event, you need to configure this webhook by specifying the postURL and the response format (XML or JSON).
Survey response data will be the same as that received from /survey/response/<ResponseId> API call.

Events Webhook

Triggers when the specified event gets logged into the system. To add a webhook specific to an event, you need to configure this webhook by specifying the name of the event and the postURL. Currently only JSON response format is supported.

Below is an example of how the event data for push_notification_accepted event looks like

{
    "event_data": {
        "result": "SUCCESS" // push-notification sent succefully
    },
    "system_data": {
        "variation_id": "1if30if",
        "sdk": "ANDROID",
        "scope":"~7l798ci",
        "id": "20hlgbg",
        "push_notification_content": "{\"identifier\":\"1if30if\",\"experimentId\":\"20hlgbg\",\"packageName\":null,\"title\":\"Master App\",\"message\":\"How are you today ?\",\"image\":null,\"cta\":{\"id\":\"3d7630c9\",\"type\":\"DEEP_LINK\",\"actionLink\":\"webengage://com.webengage.testapp1/start_activity/com.webenagege.testapp1.Activity1\",\"actionText\":null,\"templateId\":null},\"custom\":[{\"key\":\"theKey\",\"value\":\"whatIsKey\"}],\"expandableDetails\":{\"title\":null,\"image\":\"https://webengage.net/wk-test-static-files/~99199077/6313a242-91a5-46b8-96b5-1598365a509a.jpg\",\"message\":null,\"cta1\":null,\"cta2\":null,\"cta3\":null,\"style\":\"BIG_PICTURE\",\"category\":null},\"tokens\":null}"
    },
    "event_time": "2016-06-01T15:53:59+0000",
    "event_name": "push_notification_accepted",
    "license_code": "~99199077",
    "category": "system",
    "user_id": "john@doe.com",
    "anonymous_id": "0000014a-a2da-cfd3-91c7-0252d7df1a4c"
}

Below is an example of how the event data for push_notification_rejected event looks like

 {
     "event_data": {
         "result": "UNAVAILABLE"
     },
     "system_data": {
         "variation_id": "1if30if",
         "sdk": "ANDROID",
         "scope":"~7l799ci",
         "id": "20hlgbg",
         "push_notification_content": "GCM_ERROR"
     },
     "event_time": "2016-06-01T15:53:58+0000",
     "event_name": "push_notification_rejected",
     "license_code": "~99199077",
     "category": "system",
     "user_id": "john@doe.com",
     "anonymous_id": "0000014a-a2da-cfd3-91c7-0252d7df1a4c"
 }

Journey Webhook

Triggers on Journey create, update, publish and delete events. To add a webhook specific to a journey, you need to configure this webhook by specifying the postURL. `Currently only JSON response format is supported.

Below is an example of how the event data for journey_activated event looks like

{
    "category": "account",
    "resource": "Journey",
    "version": 1,
    "event_name": "journey_activated",
    "event_time": "2017-03-06T11:00:52+0000",
    "license_code": "311c48b3",
    "user_id": "john@doe.com",
    "event_data": {
        "creationTime": "2017-03-06T11:00:52+0000",
        "createdBy": "john@doe.com",
        "name": "Repeat Order Journey",
        "id": "abn3jj5",
        "activatedBy": "john@doe.com",
        "activationTime": "2017-03-06T11:00:52+0000",
        "status": "ACTIVE",
        "tags": ["premium-user"]
    }
}

Webhooks