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:

• Event attribute 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.

Requirements

• Tealium EventStream or Tealium AudienceStream

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 you exceed the rate limit, Tealium will send an HTTP 429 response indicating too many requests.

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

POST method

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

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

https://collect.tealiumiq.com/integration/event/ACCOUNT/PROFILE/DATA_SOURCE_KEY

Use the optional tealium_trace_id query parameter (tealium_trace_id=TRACEID) to support debugging with 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

AudienceStream tracks visitors using a combination of:

• Anonymous ID: An ID usually used to track the visitor anonymously (for example, from a device or browser). In the case of a known visitor, you can use a value based on a user identifier.
• User Identifier: Sent after the visitor is known. Based on a value that identifies the user instead of a particular device.

Anonymous ID

The Anonymous ID is an anonymous identifier used by AudienceStream to associate a visitor between events and visits. Ensure this value is a GUID and consistent for the visitor. This value must also be unique to each server-side profile.

The key name of the anonymous ID is tealium_visitor_id.

Depending on your business case, you can use anonymous values or values based on known user identifiers.

Anonymous values

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 following:

• Account

• Profile
  Including the profile name ensures the tealium_visitor_id is unique to each server-side profile, which is essential when the same visitor profile is sent to multiple server-side profiles within a region.

• Visitor ID attribute ID and value

  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.

• Value in the tealium_visitor_id parameter

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 formatted 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",
    "customer_number"    : "45653454", 
    "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.

User Identifiers

When using AudienceStream, you can pass a known user identifier with a tracking call. For example, email_address or login_id.

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

In AudienceStream, these user identifiers are used to enrich visitor ID attributes.

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.