Setup a Custom Webhook

Learn how to use create and use webhooks and use dynamic template variables

Yosi Dahan avatar
Written by Yosi Dahan
Updated over a week ago

What Is a Webhook?

A webhook (also called a web callback or HTTP push API) is a way for an app to provide other applications with real-time information. A webhook delivers data to other applications as it happens, meaning you get data immediately. Unlike typical APIs where you would need to poll for data very frequently in order to get it real-time. This makes webhooks much more efficient for both provider and consumer.

Grab Your Webhook URL

You can find your notification's webhook URL by selecting your notification from the main list.

Dynamic Message Template

You can define template variables in the notification message to show dynamic data from the webhook in your notification:

Note that you can use dot notation to show data from nested fields in the webhook payload, in case you're using getting webhooks from some platform an unable to change the webhook strucutre.

The payload data will only be collected if the message template contains variables.

Basic Webhook Request

Use the POST HTTP method method for all of your webhook requests.

Optional Fields: Conversion Notification webhooks don't need any of the parameters below, a simple HTTP POST request is enough.

Stream Only POST Body Parameters

Automatic Email Search: We search for an email address inside the webhook data automatically, but we still recommend sticking to the format below.

Request Headers

Make sure your Content-Type header matches the POST body format:

  • For JSON make sure it's Content-Type => application/json

  • For form data make sure it's Content-Type => application/x-www-form-urlencoded

Basic Parameters

The parameters are used in Stream notification webhooks only:

  • (required) email - required, the email associated with the conversion/lead (string). The email must be unique for each event.

  • timestamp - a numeric timestamp in milliseconds or seconds (integer)

  • ip - the user's IP, to display the converting user's location, Geo IP (string)

  • firstName - the lead's first name (displayed in the notification), if not provided we'll lookup the name using the email

  • lastName - the lead's last name (only first letter is shown in the icon/avatar), if not provided we'll lookup the name using the email

    "email": "",
    "timestamp": 1528611279398, //optional
    "ip": "", //optional
    "firstName": "John", //optional
    "lastName": "Smith" //optional
"guid": "id" //optional, product/category identifier

Location Parameters

Parameters associated with the conversion/lead's location, alternative to Geo IP location (optional):

  • city - the city

  • country - the country (if omitted will lookup using countryCode)

  • countryCode - the country code (if omitted, will lookup using country)

  • state - the state name (relevant for the US only, if omitted, will lookup using stateCode)

  • stateCode - the state code (relevant for US only, if omitted, will lookup using state)

    "city": "Miami",
    "country": "United States",
    "countryCode": "US",
    "state": "Florida",
    "stateCode": "FL"

Purchase Parameters

The product can be displayed after the notification's message text and have the notification automatically link to the product.
Purchase related properties (optional):

  • productName - the name of the product (will be appended to the message text)

  • productLink - the link/URL the product page (will redirect to this link on click)

  • productImage - the link/URL to the product image (will display in the notification image)

  • total - purchase total amount

  • currency - the order amount currency

    "total": 55,
    "currency": "USD",
    "productName": "Sneakers", //required
    "productLink": "", //required
    "productImage": ""

Multiple Products Parameters

Purchases that have multiple products/line items (optional).
If the products have price the most expensive one is displayed, otherwise the first one is displayed:

products - array of products associated with event (object properties):

  • (required) name - product's name to display in notification (will be appended to the message text).

  • (required) link - link to the product page

  • id - the product's id

  • image - product's image (optimal: 72x72 image)

  • price - product's price

  • quantity - number of items purchased

    "products": [{
        "name": "T-Shirt", //required
        "link": "", //required
        "id": 123, //can be a string
        "image": "",
        "price": 55,
        "quantity": 2

And the result:

Did this answer your question?