Webhook

Whenever a user completes an analysis in your funnel, we can send a webhook to a URL of your choice. This can be used to trigger further actions in your system, e.g. sending an email, adding the user to a mailing list, add user/event to your CRM, etc.

Setup

To enable the webhook, you need to set your webhook URL in your funnel's settings in our app.

Webhook payload

The webhook will be sent as a POST request with a JSON body. The body will contain the following properties:

Property	Type	Description
`action`	`string`	"AskStella Analysis Completed" (Name of event)
`askstella_funnel_name`	`string`	Short name of the funnel in which this analysis was performed (the subdomain of the funnel)
`askstella_funnel_value`	`string`	A custom value you can define in the webhook settings
`askstella_analysis_id`	`string`	The analysis ID in our system
`askstella_analysis_url`	`string`	URL of the analysis results page for this user
`askstella_analysis_result`	`string`	One of our color types (LIGHT, LIGHT_WARM, WARM, DEEP, VERY_DEEP, SOFT_LIGHT, SOFT_MEDIUM, SOFT_DEEP, SOFT_VERY_DEEP, CLEAR)
`askstella_first_name`	`string`	First name of the user
`askstella_last_name`	`string`	Last name of the user
`askstella_email`	`string`	Email of the user
`askstella_hair_color`	`string`	The hair color the user selected (VERY_LIGHT, MEDIUM_BLONDE, LIGHT, RED_BLONDE, RED, MID_BROWN, BROWN, BLACK)
`askstella_eye_color`	`string`	The eye color the user selected (BLUE, GREY, GREEN, GREEN_BROWN, AMBER, BROWN, DARK_BROWN)
`askstella_skin_color`	`string`	The skin color the user selected (FAIR, LIGHT, MEDIUM_LIGHT, MEDIUM, MEDIUM_DEEP, DEEP)
`askstella_skin_undertone`	`string`	The skin undertone the user selected (WARM, COOL, NEUTRAL)
`askstella_query_string`	`string`	The query string of the URL that led the user to the analysis (e.g. utm parameters you used)
`askstella_products_all`	`array of basic product data`	One entry per recommended variant (see how product arrays are ordered below). Each item has the shape described in the product fields table.
`askstella_[funnel_subdomain]_all`	`array of variant IDs`	Variant IDs in the same order as askstella_products_all, but each item is only { VariantId: string }. VariantId is the variant ID from your shop system (e.g. Shopify). The key uses your funnel's subdomain, e.g. askstella_mybrand_all.
`askstella_[funnel_subdomain]_[tab_crm_name]`	`array of variant IDs`	For each result-page tab, an array of { VariantId: string } (shop system variant ID). The key uses your funnel's subdomain and the tab's CRM name (e.g. askstella_mybrand_bestseller). If a tab's CRM name is "all", the key is askstella_[subdomain]_tab-all to avoid colliding with the _all list.

In addition, if you have generic "single selection" steps in your funnel, we will also send the selected value of these steps as properties. The property name will be the step's key name and the key of the value:

askstella_[Step Key]: [Options Key]
e.g. askstella_skin_dryness: VERY_DRY

Each product in the product list (askstella_products_all) will have the following properties:

Property	Type	Description
`title`	`string`	Name of the product
`image`	`string`	Link to the product image
`short_description`	`string`	Short description of the product
`color`	`string`	HEX Color of the product
`link`	`string`	Link to the product page (including the variant ID if necessary)

How product arrays are ordered

All product-related arrays (askstella_products_all, askstella_[subdomain]_all, and each askstella_[subdomain]_[tab]) share one recommendation order. That order is computed when the analysis is completed, based on your funnel's result-page tab configuration and the recommended variants for this analysis.

Tabs define product sequence. When the funnel uses result-page tabs, products are ordered by walking tabs in ascending tab and within each tab by ascending product row. The first time a product appears in that walk sets its position in the global list; if the same product is configured on multiple tabs, it is not duplicated in the global order.
Variants of one product stay together. All variants of a product are grouped in one block, in the same relative order the recommendation produced for that product.
Products not on any tab. Recommended variants whose product is not assigned to any result tab are appended after the tabbed products, preserving their original relative order among themselves.
No tabs. If the funnel has no product tabs on the result page, the products/variants are ordered by name.
Per-tab variant arrays.Each tab's array is a filter of that global order: only variants whose product belongs to that tab are included, but their sequence matches the global list. A product assigned to several tabs contributes its variants to each of those tab arrays.

Secure your endpoint

The optional api key you can provide in the webhook settings will be sent in the Authorization header of the request. You can then check for this header in your endpoint to ensure the request is coming from us. Of course also make sure that your endpoint will be called with https.

headers: {
  Authorization: `API-Key ${apiKey}`,
  "Content-Type": "application/json",
  Accept: "application/json",
},

Webhook

Table of Contents

Setup

Webhook payload

How product arrays are ordered

Secure your endpoint