CleverTap webhooks enable developers to monitor specific user events and receive push notifications to their server when those events happen.

Overview

CleverTap webhooks are often used to trigger business workflows. For example, let’s say 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 ecommerce companies and cart abandonment. Let’s say 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 will send a webhook as a 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.

The rest of this page walks through how to create your first CleverTap webhook.

Step 1: Set Up Webhook in CleverTap Dashboard

Go to the Messages page of the CleverTap dashboard. Click on the + Message button.

Image replacement

Image replacement

Click on the Webhooks button.

Image replacement

Image replacement

If you have an existing segment that you want use for the webook, select that segment. Otherwise, click the + Create ad-hoc segment button.

Image replacement

Image replacement

In the Single action box, click + Create segment

Image replacement

Image replacement

Choose a name for the webhook. Click Continue to When.

Image replacement

Image replacement

On the When page, you keep the default settings and click Continue to Who. If you want to choose a different start date, end date, or add a delay for the webhook, you can modify it on this page.

Image replacement

Image replacement

Under As Soon as User Does, select App Launched. Click Continue to What.

Image replacement

Image replacement

Click Add a new webhook URL, which is where CleverTap will send the webhook.

Image replacement

Image replacement

Click + Add new

Image replacement

Image replacement

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 Requestb.in to create an endpoint for testing purposes. Click Save.

Image replacement

Image replacement

Under Webhook URL, select the one you just created. You have the option to receive email, identity, objectId (CleverTap ID), profileData (custom profile variables), and push_token for each user.

Image replacement

Image replacement

Click Continue to Overview and then Click Deploy Webhook.

Image replacement

Image replacement

Step 2: Listen for Webhooks on Your Server

In the previous step, we created a webhook to send notifications to our server when a user launches our app.

If you have CleverTap already integrated in your app, try launching your app now. Then go back to the Messages page in the dashboard. You will see a webhook was sent to your server.

Image replacement

Image replacement

Understanding Webhook errors

Webhook is a request-response type format. CleverTap sends the request and waits for one second for a response from the end point. If the end point URL fails to respond within one second, 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.

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

{
    "targetId": 1472124953,
    "key_values": {
        "PromoCode": "MT50",
        "PowerUser": "true"
    },
    "profiles": [
        {
            "Email": "jack@gmail.com",
            "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": "jill@gmail.com",
            "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"
        }
    ]
}

Next Steps

Congrats 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 like Slack. If you are interested in learning more, we have a guide that walks through sending a CleverTap webhook to Slack via Tray.io.

Webhooks


Suggested Edits are limited on API Reference Pages

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