Documentation

Webhook Templates

Suggest Edits

Overview

Lytics Webhook Templates enable the configuration of customized workflows for any destination. The setup process may vary based on the downstream provider. Below is a step-by-step guide for configuring a robust workflow with Insider.

Insider Custom Webhook Templates

Authorization

If you haven't already done so, you will need to setup an Insider account before you begin the process described below.

To authorize an Insider workflow, you must provide an Insider API key so Lytics can communicate with Insider's APIs to send and receive data from your account. For instructions on how to create an API key, refer to Insider's API key documentation.

  1. Select Insider from the list of providers.

  2. Select the API Key method for authorization.

  3. Enter a Label to identify your authorization.

  4. (Optional) Enter a Description for further context on your authorization.

  5. Enter the Insider API Key that you generated.

  6. Click Save Authorization.

To successfully send requests to the Insider APIs via Lytics webhook workflow, we must create an authorization using the key and secret outlined below.

Select Provider

This integration leverages our Webhook integration to connect with and retrieve data from Ansira's endpoints. Begin by selecting the Webhooks provider tile.

Select Method

Next, select an authorization method. If this is your first time creating an authorization for Insider, select Provide authorization as request header or parameter.

Configure Authorization

Next, we'll configure the authorization to use a request header and request parameter provided by Insider. Please configure all fields as outlined below and leave any additional fields blank unless you fully understand the implications.

Label

Create a label for your authorization. This will only surface in the Lytics UI for easy navigation when selecting the authorization in additional workflows or reviewing the details and logs.

Description

Add an optional description to provide context for where the auth came from and how it will be used.

Webhook Request Headers

Insider will provide both the X-PARTNER-NAME and the X-REQUEST-TOKEN. 

X-PARTNER-NAME: XXXXXXX
X-REQUEST-TOKEN: XXXXXXX

Webhook Request Parameters

Leave this field blank.

Audience Entrance Triggers

Integration Details

  • Implementation Type: Server-side Integration.
  • Implementation Technique: REST API Integrations - Audience Trigger Integration - Webhook Integration
  • Frequency: Real-time Integration that continuously enriches users as they fall into a source audience.
  • Resulting data: Updated profile in Insider with the correct segment membership.

This integration utilizes the Lytics' Audience Trigger Webhook to send a secure request to Insider when a user enters the source audience. This request is sent to the POST api/user/v1/upsert endpoint and contains user data configured within the template described below to send a Lytics profile with extended information about that user to Insider. The Insider upsert API docs will inform on the type of information that can be sent. We'll outline the following steps to enable this enrichment workflow:

  1. Create an Authorization to Insider
  2. Create a source audience to determine which profiles need to be sent.
  3. Create a webhook template to format the outbound request to send new segment membership to Insider APIs correctly.
  4. Create the real-time webhook syncs between Lytics & Insider using the corresponding templates.
  5. Validate that the webhook flow is working as expected.

Authorization

Select or configure a new authorization as outlined above.

Create Webhook Template

Webhook templates are created using jsonnet. These templates provide a flexible way to reformat the outbound payload of a webhook request to meet the recipient's requirements. In this case, we'll create a template that provides the proper formatting of identifiers, attributes, and event data for the Insideruser API. This step may appear to be technical. As such, if you need assistance, please contact your technical account manager or primary point of contact.

The example below shows how to structure the template in order to send segment entrances, segment metadata, and profile attributes to Insider. The Insider upsert API docs has more information on how the data should be structured if there are additional questions. 

echo 'local event = (import "lytemplates.libsonnet");
local eventDetails = event.get("segment_events", "")[0];
{
  "users": [
    {
      "insider_id": event.get("insider_id", ""),
      "identifiers": {
        "email": event.get("email", ""),
        "custom": {
          "lytics_id": event.get("_id", ""),
          "lytics_last_uid": event.get("_uid", "")
        }
      },
      "attributes": {
        "email": event.get("email", ""),
        "phone_number": event.get("phone", ""),
        "name": event.get("first_name", ""),
        "surname": event.get("last_name", ""),
        "gender": event.get("gender", ""),
        "age": event.get("age", ""),
        "language": event.get("user_language", ""),
        "country": event.get("visit_country", ""),
        "city": event.get("visit_city", ""),
        "email_optin": event.get("consent_email_status", ""),
        "gdpr_optin": event.get("consent_gdpr_status", ""),
        "sms_optin": event.get("consent_sms_status", ""),
        "whatsapp_optin": event.get("consent_whatsapp_status", ""),
        "custom": {
          "status":  event.get("status", ""),
          "lytics_computed_attr": event.get("_segments", [""]),
          "score_consistency": event.get("score_consistency", ""),
          "score_frequency": event.get("score_frequency", ""),
          "score_intensity": event.get("score_intensity", ""),
          "score_maturity": event.get("score_maturity", ""),
          "score_momentum": event.get("score_momentum", ""),
          "score_propensity": event.get("score_propensity", ""),
          "score_quantity": event.get("score_quantity", ""),
          "score_recency": event.get("score_recency", ""),
          "score_volatility": event.get("score_volatility", ""),
          "lytics_content": event.get("lytics_content", ""),
          "lytics_content_inferred": event.get("lytics_content_inferred", ""),
          "lytics_rollup": event.get("lytics_rollup", ""),
          "segment_prediction_percentile": event.get("segment_prediction_percentile", "")
        }
      },
      "not_append": true,
      "events": [
        {
          "event_name": "lytics_trigger",
          "timestamp": eventDetails["enter"],
          "event_params": {
            "custom": {
              "id": eventDetails["id"],
              "audience": eventDetails["slug"],
              "trigger": eventDetails["event"],
              "origin": "Lytics"
            }
          }
        }
      ]
    }
  ]
}' | http -v POST https://api.lytics.io/v2/template name==insider_temp type==jsonnet account_id=={YOUR-ACCOUNT-ID} key=={YOUR-API-TOKEN}

Jsonnet is highly customizable. In the example above, we pull the email from the profile and hard code a language If the desire is for the language to be dynamic, this could also leverage the.event.get method to pull the value from each profile. If you use the dynamic method, the field name in the event.get() function is the field name that has been defined in the Lytics schema, as seen in the example below: 

echo 'local event = (import "lytemplates.libsonnet");
{
	"field_name_to_send_to_insider": event.get("lytics_field_name", ""),

}' | http -v POST https://api.lytics.io/v2/template name==insider_temp type==jsonnet account_id=={YOUR-ACCOUNT-ID} key=={YOUR-API-TOKEN}

Audience Exit triggers

Integration Details

  • Implementation Type: Server-side Integration.
  • Implementation Technique: REST API Integrations - Audience Trigger Integration - Webhook Integration
  • Frequency: Real-time Integration that continuously enriches users as they fall into a source audience.
  • Resulting data: Updated profile in Insider with the correct segment membership.

This integration utilizes the Lytics' Audience Trigger Webhook to send a secure request to Insider when a user exits the source audience. This request is sent to the POST auser/v1/attribute/delete endpoint and contains user data configured within the template described below to send a Lytics profile with extended information about that user to Insider. The Insider delete API docs will inform on the type of information that can be sent. We'll outline the following steps to enable this enrichment workflow:

  1. Create an Authorization to Insider
  2. Create a source audience to determine which profiles need to be sent.
  3. Create a webhook template to format the outbound request to send segment membership removals to the Insider APIs correctly.
  4. Create the real-time webhook syncs between Lytics & Insider using the corresponding templates.
  5. Validate that the webhook flow is working as expected.

Authorization

Select or configure a new authorization as outlined above.

Create Webhook Template

Webhook templates are created using jsonnet. These templates provide a flexible way to reformat the outbound payload of a webhook request to meet the recipient's requirements. In this case, we'll create a template that provides the proper formatting of identifiers, attributes, and event data for the Insideruser API. This step may appear to be technical. As such, if you need assistance, please contact your technical account manager or primary point of contact.

The example below shows how to structure the template to send segment exits and metadata metadata to Insider. The Insider upsert API docs has more information on how the data should be structured if there are additional questions.

echo 'local event = (import "lytemplates.libsonnet");  
local eventDetails = event.get("segment_events", "")[0];
{  
   "users":\[  
      {  
         "identifiers":{  
            "email": event.get("email", ""),  
            "custom": {  
                "lytics_id": event.get("\_uid", "")  
            }  
         },  
         "attributes":{  
            "custom":{  
              partial:{ 
                "lytics_computed_attr": event.get("_segments", [""])
              }  
            }  
         },
         "events": [
            {
              "event_name": "lytics_trigger",
              "timestamp": eventDetails["exit"],
              "event_params": {
                "custom": {
                  "id": eventDetails["id"],
                  "audience": eventDetails["slug"],
                  "trigger": eventDetails["event"],
                  "origin": "Lytics"
                }
              }
            }
          ]
      ]
    }
   ]  
}' | http -v POST <https://api.lytics.io/v2/template> name==insider_temp type==jsonnet account_id=={YOUR-ACCOUNT-ID} key=={YOUR-API-TOKEN}

Jsonnet is highly customizable. In the example above, we pull the email from the profile and hard code a language If the desire is for the language to be dynamic, this could also leverage the.event.get method to pull the value from each profile. If you use the dynamic method, the field name in the event.get() function is the field name that has been defined in the Lytics schema, as seen in the example below: 

echo 'local event = (import "lytemplates.libsonnet");
{
	"field_name_to_send_to_insider": event.get("lytics_field_name", ""),

}' | http -v POST https://api.lytics.io/v2/template name==insider_temp type==jsonnet account_id=={YOUR-ACCOUNT-ID} key=={YOUR-API-TOKEN}

Configure Webhook

In the final step, we will combine it by configuring our webhook destination to use the auth, templates, and audience to enrich a Lytics profile. It is important to ensure the auth is selected for the corresponding webhook trigger for entrances and exits. Because they have different structures, the data will not be updated properly in insider if this step is not followed.

Select Provider

This integration leverages our Webhook integration to connect with and retrieve data from Ansira's endpoints. Begin by selecting the Webhooks provider tile.

Select Job Type

Next, select the Audience Triggers Webhook job type. This webhook job will pass the response of each request to the configured data stream to be mapped back to a user's profile.

Configuration

There is a list of fields available to configure for the Lytics webhook. The details for those configurable fields can be found in the webhook documentation. Below are the required fields specific to the Lytics and Insider workflow.

Select Source Audience(s)

Select one or more audiences to enrich with Ansira data. We highly recommend following the suggested approach in the audience of this doc to prevent invalid or unnecessary calls to the Ansira API.

Select Webhook Template

Select the template that was created in the previous step.

Set Webhook URL
// if doing an entry
https://unification.useinsider.com/api/user/v1/upsert

// if doing an exit
https://unification.useinsider.com/api/user/v1/delete
Set Audience trigger Events

This should be Exit or Entrance, depending on the JSONNET template it is linked to.

Set Export Fields

Do not select any fields. This will default to syncing the entire profile based on the defined template.

Updated 4 months ago