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.
The following are built-in variables that are automatically parsed from your webhooks or platform integration (Shopify, Wix, WooCommerce, BigCommerce, etc):
{{name}}{{product.name}}(if available){{product.link}}(if available){{location.country}}(if available){{location.countryCode}}(if available){{location.state}}(if available){{location.stateCode}}(if available){{location.city}}(if available)
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 customize the webhook payload structure.
The dynamic variables will only work once the notification's message contains the relevant payload fields (i.e. old webhooks will not show the 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": "test@gmail.com",
"timestamp": 1528611279398, //optional
"ip": "141.92.55.102", //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)
{
//ALL ARE OPTIONAL
"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
{
//ALL ARE OPTIONAL
"total": 55,
"currency": "USD",
"productName": "Sneakers", //required
"productLink": "https://sneakers.com/sneakers", //required
"productImage": "https://sneakers.com/sneakers.jpg"
}
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
{
//OPTIONAL
"products": [{
"name": "T-Shirt", //required
"link": "https://mystore.com/t-shirt", //required
"id": 123, //can be a string
"image": "https://mystore.com/images/t-shirt.png",
"price": 55,
"quantity": 2
}]
}
And the result:
