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:

Table of Contents Placeholder

How It Works

A Webhook API sends outgoing requests to an endpoint that you specify. These requests inform Tealium EventStream and AudienceStream about customer activity from your external systems.

• When you add a webhook data source, a unique endpoint is generated.
• This endpoint is used to configure a webhook in your external system.
• Once configured, you can create subscriptions based on topics and receive related push notifications to automate use cases, stay informed, and increase productivity.

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 objects. Events sent using HTTP POST with a complex JSON object will be flattened as follows:

• Event keys are created by lowercasing and connecting key paths to a prefix. For example, a value of true located at alpha.beta displays as "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 do not have the ability to modify the request to meet format requirements for the standard Tealium Collect endpoint.

Requirements

• Tealium EventStream or Tealium AudienceStream

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.
tealium_visitor_id	Optional* For use with AudienceStream

If batched events are being used and there is no tealium_visitor_id present in the event, all events in the same batch generate the same tealium_visitor_id. This implies that the events will be tied together in the same visitor profile, regardless of visitor stitching.

Setup

The following sections provide guidance on how to add the HTTP API - Advanced data source and create a webhook.

Add the Data Source

The HTTP API - Advanced data source supports both the GET and POST methods using the following endpoint:

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

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

Examples

The following sections provide examples of input code and the resulting (flattened) output for complex objects.

Complex Object

Before Flattening

{
    "boolean": true,
    "number": 12.34,
    "string": "value",
    "array_of_strings": ["first", "second"],
    "array_of_arrays": [
        [1, 2],
        [3, 4]
    ],
    "array_of_objects": [{
        "ordinal": "first"
    }, {
        "ordinal": "second"
    }],
    "object": {
        "child_boolean": true,
        "child_number": 12.34,
        "child_string": "value",
        "child_array_of_strings": ["first", "second"],
        "child_array_of_arrays": [
            [1, 2],
            [3, 4]
        ],
        "child_object": {
            "gchild_boolean": true,
            "gchild_number": 12.34,
            "gchild_string": "value",
            "gchild_array_of_strings": ["first", "second"],
            "gchild_array_of_arrays": [
                [1, 2],
                [3, 4]
            ]
        }
    }
}

After Flattening

{
    "boolean": true,
    "number": 12.34,
    "string": "value",
    "array_of_strings": ["first", "second"],
    "array_of_arrays": ["[1,2]", "[3,4]"],
    "array_of_objects": ["{\"ordinal\":\"first\"}", "{\"ordinal\":\"second\"}"],
    "object_child_boolean": true,
    "object_child_number": 12.34,
    "object_child_string": "value",
    "object_child_array_of_strings": ["first", "second"],
    "object_child_array_of_arrays": ["[1,2]", "[3,4]"],
    "object_child_object_gchild_boolean": true,
    "object_child_object_gchild_number": 12.34,
    "object_child_object_gchild_string": "value",
    "object_child_object_gchild_array_of_strings": ["first", "second"],
    "object_child_object_gchild_array_of_arrays": ["[1,2]", "[3,4]"]
}

JSON Object

Before Flattening

A JSON object is treated as a single event by default.

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

After Flattening

Unless the parser is overwritten by custom logic used to parse out batched events, the JSON object is transformed into a single event with stringified JSON array values.

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