HTTP API - Advanced Incoming Webhook Setup Guide

[#1]

This article describes how to use the HTTP API - Advanced data source to create an HTTP endpoint to collect real-time event data with support for flattening complex objects.

In this article:

• How It Works
• Batched Events
• Requirements
• Request Format
• API Endpoint
• Supported Parameters
• Adding the Data Source
• Response Codes
• Examples
• JSON Object
• Example 1
• Example 2
• Complex Object
• Before Flattening
• After Flattening
• Limitations

How It Works

The HTTP API - Advanced data source is a generic data source that can conditionally parse incoming request bodies. This data source offers an HTTP endpoint to collect real-time event data with support for flattening complex objects. The endpoint is flexible and can be implemented as a tracking pixel in a web page or as a JSON API in your custom application.

This data source is similar to the HTTP API data source, but with additional support for complex JSON objects. Events sent using HTTP POST with a complex JSON object will be flattened as follows:

• The event attributes names are created by lower-casing and joining the object properties with an underscore ("_"). For example:
  Source data: "alpha" : { "beta" : true }
  Flattened event attribute: "alpha_beta" : true
• Numbers, Booleans, and strings inside of an array are preserved.
• Objects and arrays inside of an array are stringified.

Use this data source type when you need to send data in real-time and cannot modify the request to meet format requirements for the standard Tealium Collect endpoint.

Batched Events

The HTTP API - Advanced data source HTTP endpoint supports multiple events in a single request. These events are called batched events. For batched events, you receive one response code based on the status of all records. If a single record/event fails, only that event fails, the rest is processed.

Requirements

• Tealium EventStream or Tealium AudienceStream

Request Format

The HTTP API - Advanced data source supports both the GET and POST methods.

API Endpoint

Use the following endpoint to access the HTTP API - Advanced data source:

https://collect.tealiumiq.com/integration/event/ACCOUNT/PROFILE/DATA_SOURCE_KEY?tealium_trace_id=TRACEID

Supported Parameters

The following default parameters are supported in each request:

Parameter	Description
tealium_event	(Optional) The name of the event.
tealium_trace_id	(Optional) For use with Trace. Must be set as a query string parameter. Example: ?tealium_trace_id=abc123456
tealium_visitor_id	(Optional) For use with Tealium AudienceStream. If tealium_visitor_id is not set in a batched event request, all events in the batch get the same generated anonymous ID value. This implies that the events will be tied together in the same visitor profile, regardless of visitor stitching.

Adding the Data Source

This section provides guidance on how to add the HTTP API - Advanced data source and create a webhook.

Add the HTTP API - Advanced data source before proceeding, then copy the generated endpoint for use in an external system.

Related: How to Add a Data Source

Response Codes

Response Code	DESCRIPTION
HTTP 204	Request Successful
HTTP 400	Malformed JSON request
HTTP 404

Examples

The HTTP API - Advanced Incoming Webhook is useful when you want to send an HTTP API Advanced call using Javascript, bash scripting or curl.

JSON Object

Example 1

By default a JSON array will be treated as several events; so:

[
  {
    "Id": "1",
    "Detail": {
      "Name": "Event A"
    }
  },
  {
    "Id": "2",
    "Detail": {
      "Name": "Event B"
    }
  }
]

Will be transformed into several events:

 // First Event
  {
    "Id": "1",
    "detail_name":  "Event A"
  }
  
  // Second Event
  {
    "Id": "2",
    "detail_name":  "Event B"
  }

Example 2

Before Flattening

{
    "events": [
        {
            "id": "1",
            "name": "Event A"
        },
        {
            "id": "2",
            "name": "Event B"
        },
        {
            "id": "3",
            "name": "Event C"
        }
    ]
}

After Flattening

{
    "events": [
        "{\"id\":\"1\",\"name\":\"Event A\"}",
        "{\"id\":\"2\",\"name\":\"Event B\"}",
        "{\"id\":\"3\",\"name\":\"Event C\"}"
    ]
}

Complex Object

This section provides examples of input code and the resulting (flattened) output for complex objects.

Before Flattening

The following purchase event example shows how client-side e-commerce events with complex objects get flattened.

{
  "ecommerce": {
    "event": "purchase",
    "purchase": {
      "customer": {
        "id": "8237572",
        "email": "john.smith@example.com",
        "city": "San Diego",
        "state": "CA",
        "country": "United States"
      },
      "order": {
        "id": "ORD123456",
        "store": "mobile web",
        "subtotal": "2524.00",
        "total": "2549.00"
      },
      "product": {
          "name": ["Product One", "Product Two"],
          "id": ["PROD123","PROD456"],
          "price": ["12.00","1250.00"],
          "brand": ["Ralph Lauren","Lucky"],
          "category": ["Apparel","Apparel"],
          "quantity": [1,1]
        }
    }
  }
}

After Flattening

After flattening, the purchase event becomes:

{
    "ecommerce_event": "purchase",
    "ecommerce_purchase_customer_id": "8237572",
    "ecommerce_purchase_customer_email": "john.smith@example.com",
    "ecommerce_purchase_customer_city": "San Diego",
    "ecommerce_purchase_customer_state": "CA",
    "ecommerce_purchase_customer_country": "United States",
    "ecommerce_purchase_order_id": "ORD123456",
    "ecommerce_purchase_order_store": "mobile web",
    "ecommerce_purchase_order_subtotal": "2524.00",
    "ecommerce_purchase_order_total": "2549.00",
    "ecommerce_purchase_product_name": ["Product One", "Product Two"],
    "ecommerce_purchase_product_id": ["PROD123","PROD456"],
    "ecommerce_purchase_product_price": ["12.00","1250.00"]
    "ecommerce_purchase_product_brand": ["Ralph Lauren","Lucky"],
    "ecommerce_purchase_product_category": ["Apparel","Apparel"],
    "ecommerce_purchase_product_quantity": [1,1]
}

Limitations

• The maximum Payload size is 3.5 MB.
• The number of records that can be processed per request is limited by the payload size.