Overview

CleverTap webhooks enable developers to monitor specific user events and receive push notifications to their server when those events happen. CleverTap webhooks are often used to trigger business workflows. For example, if you want to get notified every time a user looks up an international flight in business class but then doesn’t book the flight within 30 minutes. You can set up a webhook in CleverTap to monitor for this specific event, get notified when it happens, and then trigger a process in your call center to contact the user to complete the booking.

Another popular use case for CleverTap webhooks is with e-commerce companies and cart abandonment. For example, if a user abandons their cart during a high-value transaction. You can set up a webhook in CleverTap to monitor for this specific event, get notified when it happens, and then trigger a call center workflow to contact the user to solve any issues and complete the purchase.

There are six categories of webhooks that you can create to monitor user events. The table below describes each of those categories.

Type
Description
Example

Single action

User performed an action.

User launched the app.

Actions

User performed multiple actions.

User launched the app and viewed a notification.

Inaction within time

User performed an action, but does not perform another action within a certain time.

User has not launched the app in three days.

Inaction

Users performed an action, but did not perform another action.

User launched the app, but did not view a notification.

Date time property

Period of time after a date time property on a user event.

User purchased an item and three days have passed.

Actions with user properties

Performed an action or not, filtered by their demographic properties.

User purchased an item and lives in Canada.

Webhooks are created in the CleverTap dashboard by defining a user segment and a callback URL on your server. CleverTap sends a webhook as an HTTP POST with information about the event when it occurs. You can customize the webhooks to use basic authentication and include any custom properties if needed.

Perform the following steps to create your first CleverTap webhook.

Step 1: Set Up Webhook in CleverTap Dashboard

  • Go to Settings > Engage > Channels > Webhooks.
  • Click +Add Webhook.
  • Update the webhook template.

Note

Add a webhook name and destination URL. If you currently don’t have an endpoint created on your server to receive the webhook, you can use www.Requestbin.com to create an endpoint for testing purposes.

  • Click Save.

Step2: Create a Webhook Campaign

  • Go to Campaigns from the CleverTap dashboard.
  • Click + Campaign. The channels page displays.
  • Click Webhooks under Server channels.
  • Select the campaign type.
  • Select when to send the campaign.

Note

If you specify a recurring day for a campaign, such as the 7th of each month, then the campaign will start for the specified day and ignore the creation date. This is a precaution to avoid sending a campaign unintentionally on a prior date.

If you have an existing segment you want to use for the webhook, select that segment; otherwise, click the +Create ad-hoc segment button.

In the Single action box, click +Create an ad-hoc segment, and then enter details and click Continue.

  • Select webhook URL from the list.
  • Add query parameters in URL key-value pairs.

Note

You can also click the Add a new webhook URL to create a new Webhook URL. You will be redirected to the settings page. Refer to Set up a Webhook.

  • Select the content-type (JSON or plain text)
  • Add the Webhook content to send or receive the data.

You can either use Profile Variables or Custom body. You can also add personalization with "@" here. You have the option to send/receive an email, identity, objectId (CleverTap ID), profileData (custom profile variables), and push_token for each user.

You can also choose a custom payload.

The preview for your payload is displayed on the right side of the pane. The final view will look similar to the following:

Liquid Tags

Liquid tags offer flexibility in composing your message. You can have fixed or variable values and change the look and feel of your message by using Liquid tags.

Each notification is personalized to the receiver.

Hello John!

Here is a special coupon for you: Gold4All

For more information on using tags, see Liquid Tags.

Linked Content

Linked Content gives you the ability to personalize messages with rich and contextual data that is available outside of the CleverTap platform. Linked Content helps you to send messages with send-time personalization.

For example, you deliver food across different geographies and you want to personalize offers to each user based on the weather on their location. The location can come from CleverTap personalization and the weather information can come from an API that provides the current weather. If you want to add more information, you can opt for any source such as third-party tools and in-house software to include in your message.

For more information on using Linked Content, see Linked Content.

  • Click the send a test webhook link to test if your webhook is set up and working correctly.
  • Apply control groups, if required.
  • Click Continue. Check the Overview and deploy the webhook.

Step 3: Listen for Webhooks on Your Server

In the previous step, we created a webhook to send notifications from our server when a user makes a purchase.

Understanding Webhook Errors

Webhook is a request-response type format. CleverTap sends the request and waits for three seconds for a response from the endpoint. If the endpoint URL fails to respond then CleverTap retries the request. If the retry also fails, the campaign stats page is updated with the error "Webhook Dispatch Failed."

Also, another probable cause for the error is if the webhook endpoint is temporarily unavailable or down.

Sample payload

Following is a sample webhook payload containing all possible fields for profile variables. The targetId corresponds to the webhook campaign ID for which you are receiving the payload.

{
    "targetId": 1472124953,
    "key_values": {
        "PromoCode": "MT50",
        "PowerUser": "true"
    },
    "profiles": [
        {
            "Email": "[email protected]",
            "Identity": "foo",
            "ObjectId": "-g55b74fb1030740e4a4931910a8abb862",
            "ProfileData": {
                "Last Score": 308,
                "High Score": 308,
                "Replayed": true
            },
            "Event_properties": {
                "Score": 1200,
                "Game Mode": "Practice",
                "Rating": 1
            },
            "Push_token": "19403aa5d3bb376769a8101c9cbf22159cb1836117659cc684a71243589982ea"
        },
        {
            "Email": "[email protected]",
            "Identity": "bar",
            "ObjectId": "__g09c9bf3b0d374a259c86f5b855ec9b19",
            "ProfileData": {
                "Last Score": 309,
                "High Score": 309,
                "Replayed": true
            },
            "Event_properties": {
                "Score": 500,
                "Game Mode": "Tournament",
                "Rating": 2
            },
            "Push_token": "fiCjRO_opjw:APA91bH0yzS_eBj1Xx8TcakMzz4yTc3id29A79GOjnaaMtIQLrjztNfzzRz7slqWmNzndECx_hHh7qiL0LZJOkGwzr9Zp_g1mC9B6BVuEbsjrMFoxXX830zMRuvxtU_AhFTC0JPHejZh"
        }
    ]
}

View Statistics

You can view the statistics of your webhook from the Campaign list page.

Congratulations on creating your first CleverTap webhook!

Another option besides setting up an endpoint on your server to listen for CleverTap webhooks is using a workflow automation tool, such as Tray.io or Zapier. These tools can help integrate a CleverTap webhook without any code and then send these notifications to other systems such as Slack. If you are interested in learning more, we have a guide that walks through sending a CleverTap webhook to Slack via Tray.io.

Updated 13 days ago


Webhooks


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.