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.
Basic Webhook Request
Use the POST method for all of your webhook requests.
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.
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
The parameters are used in Stream notification webhooks only:
- (required) email - required, the email associated with the conversion/lead (string)
- 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
"timestamp": 1528611279398, //optional
"ip": "22.214.171.124", //optional
"firstName": "John", //optional
"lastName": "Smith" //optional
"guid": "id" //optional, product/category identifier
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
"country": "United States",
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
"productName": "Sneakers", //required
"productLink": "https://sneakers.com/sneakers", //required
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
"name": "T-Shirt", //required
"link": "https://mystore.com/t-shirt", //required
"id": 123, //can be a string
And the result: