HTTP API - Advanced incoming webhook setup guide

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 that allows you to collect real-time event data in a single HTTP call with support for complex objects flattening and batched events. 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 and batching. 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 and the rest is processed.

Rate limits

The HTTP API - Advanced data source supports a maximum rate limit of 100 events/second.

For example, if you send

• 1 event per call, you can send 100 calls/second.
• 10 events per call, you can send 10 calls/second.
• 100 events per call, you can send 1 call/second.

If your business needs require event limits, contact your Tealium account manager.

Requirements

• Tealium EventStream or Tealium AudienceStream

Request format

The HTTP API - Advanced data source supports the POST method. For GET method requests, use the HTTP API.

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

The use of the tealium_trace_id query parameter is optional and should be used only when debugging the Trace tool. For more information about using a trace, see About Trace.

To find your data source key, navigate to the Data Sources dashboard, click the data source you want to use, and copy the key from the Data Source Key field.

Visitor identifiers

AudineceStream tracks visitors using a combination of:

• Primary Visitor ID: Used to track the visitor anonymously.
• Secondary Visitor ID: Sent additionally once the visitor is known.

Primary Visitor ID

The primary visitor ID is an anonymous identifier used by AudienceStream to associate a visitor between events and visits. This value should be a GUID (Globally Unique Identifier) and should be consistent for the visitor.

In the HTTP API Advanced webhook, the key name of the primary visitor ID is tealium_visitor_id.

Depending on your business case, you can use anonymous visitors or known visitors.

Anonymous visitors

If you are using Tealium iQ Tag Management and sending API calls server-to-server to enrich anonymous visitor profiles, then the value of the tealium_visitor_id must match the value in the utag_main_v_id cookie. For more information about the built-in variables from utag.js, see JavaScript (Web) > Data Layer.

If you are using Adobe Launch or Google Tag Manager, then the value needs to match the v part of the TEAL cookie.

Known visitors server-to-server

When sending data for known visitors (when a value exists for a Visitor ID attribute such as email_address), include a concatenation of the account, profile, visitor ID attribute ID and value and the value in the tealium_visitor_id parameter.

You can find the visitor ID attribute ID next to the attribute name in the attribute list or within the expanded details. For more information, see About Attributes.

For example, for the following values:

• Account name: my-account
• Profile: main
• Visitor ID attribute ID: 7688
• Customer number value you want to pass: 45653454

you would concatenate these values in the following way:

"tealium_visitor_id":"__my-account_main__7688_45653454__"

Ensure that your tealium_visitor_id is formatted correctly before proceeding. Incorrectly formed parameters will cause errors in AudienceStream and may not track properly.

Example JSON:

{
    "tealium_account"    : "my-account",
    "tealium_profile"    : "main",
    "tealium_event"      : "user_login",
    "email_address"      : "user@example.com",
    "tealium_visitor_id" : "__my-account_main__7688_45653454__"
}

Whether you use anonymous visitors or known visitors, if your API calls do not contain a consistent tealium_visitor_id, each event will generate a new visit and visitor stitching will not be possible.

Secondary ID

When using AudienceStream, you can pass a known visitor identifier attribute, a secondary ID, with a tracking call. For example, email_address or login_id.

A visitor identifier is also needed if you are using EventStream and need to provide an ID to a vendor connector.

To learn more about creating visitor identifiers, see Visitor ID Attribute.

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.

The HTTP API - Advanced endpoint is not active until you add the data source and publish the profile.

Related: How to Add a Data Source

Response codes

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 array as payload

If you pass a JSON array as the entire payload, it will be treated as several events (batching).

[
  {
    "tealium_visitor_id": "503126878d17fcd6bde7df320ff6eb7c278a1c42f",
    "my_string": "12345a",
    "Detail": {
      "Name": "Event A"
    }
  },
  {
    "tealium_visitor_id": "e0f7e1bb7c5efa1afeba05fc4ddf93aa86caee629",
    "my_string": "12345b",
    "Detail": {
      "Name": "Event B"
    }
  }
]

This payload will be transformed into several events:

// First Event
  {
    "tealium_visitor_id": "503126878d17fcd6bde7df320ff6eb7c278a1c42f",
    "my_string": "12345a",
    "detail_name":  "Event A"
  }

  // Second Event
  {
    "tealium_visitor_id": "e0f7e1bb7c5efa1afeba05fc4ddf93aa86caee629",
    "my_string": "12345b",
    "detail_name":  "Event B"
  }

JSON array as key value in a payload

If you pass an array as the value of a key in the payload, the array will be flattened into an array of strings.

For example, the following array:

{
   "tealium_visitor_id": "503126878d17fcd6bde7df320ff6eb7c278a1c42f",
   "my_string": "12345a",
   "detail_name": "Event A",
   "events": [
       {
           "id": "1",
           "name": "Event A"
       },
       {
           "id": "2",
           "name": "Event B"
       },
       {
           "id": "3",
           "name": "Event C"
       }
   ]
}

will be flattened into the following array of strings:

{
   "tealium_visitor_id": "503126878d17fcd6bde7df320ff6eb7c278a1c42f",
   "my_string": "12345a",
   "detail_name": "Event A",
       "events": [
        "{\"id\":\"1\",\"name\":\"Event A\"}",
        "{\"id\":\"2\",\"name\":\"Event B\"}",
        "{\"id\":\"3\",\"name\":\"Event C\"}"
    ]
}

For complex business cases or requirements, consider using the Tealium Event Transformation functions in addition to, or instead of, the HTTP API - Advanced endpoint.

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.

{
   "tealium_visitor_id": "503126878d17fcd6bde7df320ff6eb7c278a1c42f",
   "my_string": "12345a",
   "detail_name": "Event A",
  "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:

{
   "tealium_visitor_id": "503126878d17fcd6bde7df320ff6eb7c278a1c42f",
   "my_string": "12345a",
   "detail_name": "Event A",
    "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.