Webhook Connector Setup Guide

[#1]

This article describes how to set up the Webhook Connector.

In this article:

Table of Contents Placeholder

The Webhook Connector allows you to send data to your vendor using customized HTTP requests and allows you to all aspects of an HTTP request, such as the URL, URL Parameters, Headers, Cookies, Body Content Type and Body Data. Webhook also supports a batching and a powerful templating feature designed to handle complex and dynamic data formats.

Requirements

• Tealium account enabled for EventStream (for event data)
• Tealium account enabled for AudienceStream (for visitor data)

Supported Actions

Action Name	Description	Webhook (BasicAuth)	Webhook OAuth2
Send Event Data via HTTP Request	Sends the entire event object, either as a URL-encoded JSON string or a JSON payload.	✓	✗
Send Visitor Data via HTTP Request	Sends the entire visitor profile object, either as a URL-encoded JSON string or a JSON payload.	✓	✗
Send Customized Data via HTTP Request (Advanced)	Sends individual event/visitor attributes specified via mappings	✓	✓

Event Data JSON

The expected JSON payload for events includes all of the standard attributes that are part of the event, as well as additional attributes that are native to the platform that sent the event. For example, events received from a website include DOM and cookie attributes, and events received from a mobile device include device and carrier attributes.

Event data JSON object format example:

{
    "account": "tealium",
    "profile": "main",
    "env": "prod",
    "data": {
        "dom": {
            "referrer": "",
            "domain": "tealium.com",
            "title": "Tealium | Customer Data Hub and Enterprise Tag Management",
            "query_string": "",
            "url": "http://tealium.com/",
            "pathname": "/"
        },
        "udo": {
            "tealium_event": "page_view",
            "page_name": "Tealium | Customer Data Hub and Enterprise Tag Management",
            "page_type": "home",
            "device_type": "desktop"
        },
        "firstparty_tealium_cookies": {
            "trace_id": "",
            "s_fid": "3EF757DF6253B144-0D0194366CD4479B",
            "utag_main_ses_id": 1383677957942,
            "s_cc": "true",
            "utag_main__st": 1383678970903,
            "TID": "2cff51e585ed4a5a9330324d5dbc6bb7",
            "s_sq": "[[B]]"
        }
    },
    "post_time": 1500999541000,
    "useragent": "PostmanRuntime/6.1.6",
    "event_id": "1a1ee055-1456-46f8-ab4d-779628c05dd4",
    "visitor_id": "1a1ee055145646f8ab4d779628c05dd4"
}

Visitor Data JSON

The expected JSON payload for visitors will include all of the applicable Visitor attributes for that visitor. The data object is organized by attribute type. If an attribute is not assigned it will not appear in the visitor object. The data for the current visit is also included under the "current_visit" key.

Visitor data JSON object format example:

{
    "metrics": {
        "Weeks since first visit": 0.0,
        "Lifetime visit count": 1.0,
        "Lifetime event count": 1.0,
        "Total direct visits": 1.0
    },
    "dates": {
        "Last visit": 1500999541000,
        "last_visit_start_ts": 1500999541000,
        "First visit": 1500999541000
    },
    "properties": {
        "profile": "main",
        "visitor_id": "1a1ee055145646f8ab4d779628c05dd4",
        "account": "tealium"
    },
    "flags": {
        "Is Registered": false
    },
    "audiences": [
        "New Users"
    ],
    "badges": [
        "Product Browser"
    ],
    "preloaded": false,
    "creation_ts": 1500999541000,
    "_id": "1a1ee055145646f8ab4d779628c05dd4",
    "_partition": 0,
    "shard_token": 0,
    "current_visit": {
        "metrics": {
            "Event count": 1.0
        },
        "dates": {
            "Visit start": 1500999541000,
            "last_event_ts": 1500999541000
        },
        "properties": {
            "Active browser type": "Chrome",
            "Active operating system": "MacOS",
            "Active browser version": "53",
            "Active platform": "browser",
            "Active device": "other"
        },
        "flags": {
            "Direct visit": true
        },
        "property_sets": {
            "Active devices": [
                "other"
            ],
            "Active browser versions": [
                "53"
            ],
            "Active operating systems": [
                "MacOS"
            ],
            "Active platforms": [
                "browser"
            ],
            "Active browser types": [
                "Chrome"
            ]
        },
        "creation_ts": 1500999541000,
        "_id": "9a20caf81d4adc55cfb958da81a513feff62e3324e9f840ed8bf28ca8a39a37d",
        "shard_token": 0,
        "_dc_ttl_": 60000,
        "total_event_count": 1,
        "events_compressed": false
    },
    "_dctrace": [
        "local_visitor_processor_visitor_processor"
    ],
    "new_visitor": true,
    "audiences_joined_at": {
        "tealium_main_101": 1500999542434
    }
}

Configure Settings

There are three (3) Webhook connectors to choose from based on the authorization requirements of your vendor: Webhook (BasicAuth), Webhook OAuth2 (2-Legged), and Webhook OAuth2 (3-Legged). The BasicAuth Webhook is used for services that do not require authentication or for those that only require basic authentication with a username and password. Webhook OAuth2 is used for services that explicitly require OAuth 2.0 authentication.

To get started, go to the connector marketplace and add the Webhook instance you wish to use. For general instructions on how to add a connector, see Connector Overview.

The following sections step through the configuration settings for each Webhook connector.

Webhook (BasicAuth) Configuration

This webhook supports basic HTTP authentication using the HTTP header field Authorization. The credentials are passed as a Base64 encoded string of "{ username}:{ password}".

Use the following configuration settings for the BasicAuth Webhook configuration:

1. Title (Required)
   Enter a descriptive title for the webhook.
2. BasicAuth Username
   Enter the username of your webhook's authentication.
3. BasicAuth Password
   Enter the password of your webhok's authentication.
4. Click Next or go to the Actions tab.
   The Actions tab is where you will configure the HTTP request to trigger.

Webhook OAuth2 (3-Legged) Configuration

Webhook's OAuth implementation supports server-side applications only.

Be sure to register your web application with an OAuth 2.0 service. Your application must be configured to allow the redirect URL: https://my.tealiumiq.com/oauth/webhook/callback.html

Use the following configuration settings for the OAuth2 (3-legged) Webhook configuration:

1. Client ID (Required)
   Enter the client identifier assigned to your application from the OAuth service.
2. Client Secret (Required)
   Enter the client secret assigned to your application from the OAuth service.
3. Scope
   Select the type of permission you want to request to access the application.
4. Authorization URL (Required)
   Enter the URL where you want to redirect the user after authorization.
5. Authorization URL Query Parameters
   Select one or more name-value pairs for the authorization URL. Separate multiple pairs using " &".
   • Do not use " &" at the start.
     • Correct: access_type=offline&prompt=consent
     • Incorrect: &access_type=offline&prompt=consent
6. Access Token URL (required)
   Enter the token URL to get the refresh token.
7. Click Establish Connection.

Webhook OAuth2 (2-Legged) Configuration

Tealium's Webhook OAuth2 connector allows you to send fully customized data as an http request to an API of your choice that requires OAuth2 Two- Legged authorization and supports Client Credentials and Resource Owner Password Credentials grants.

After adding the connector, use the following configuration settings for the OAuth2 2-Legged Webhook configuration:

1. Access Token URL (Required)
   Enter the API endpoint URL to request an access token from.
2. Client ID (Required)
   Enter your web application client ID.
3. Client Secret (Required)
   Enter your web application client secret.
4. Username
   Enter your username. Username is required if using Password grant type.
5. Password
   Enter your password. Password is required if using Password grant type.
6. Scope
   Select the scope of permissions to request (only required for some OAuth2 services).
7. Extra Authorization Parameters
   Add extra authorization parameters (only required for some OAuth2 services). Separate multiple parameters with &
8. Authorization Token Location
   Specify where to place the authorization token.
9. Authorization Header Prefix
   Defaults to 'Bearer' value. Specify a new value to override (only required for some OAuth2 services).

Action Parameters

The following parameters are available to all Webhook Actions.

Input Field	Required/ Optional	Template Support*	Notes
Method	Required		Supports the following methods: GET POST PUT DELETE PATCH
URL	Required	✔	Provide the URL to submit request to
URL Parameters	Optional	✔	From the Map drop-down list, select the attribute whose value you wish to send. In the To field, enter the name of the URL parameter to set.
Headers	Optional for Webhook (BasicAuth) Required for Webhook OAuth2	✔	From the Map drop-down list, select the attribute whose value you wish to send. In the To field, enter the header name which will receive the value.
Cookies	Optional	✔	From the Map drop-down list, select the attribute whose value you wish to send. In the To field, enter the cookie name which will receive the value.
Body Content Type	Optional		Specifies the "Content-Type" header. All types use the UTF-8 character set. Ignore this setting for the GET method.
Body Data	Optional	✔	Only supported for the Send Customized Data via HTTP Request Action Ignore this setting for the GET method. Provide name/value pairs if body content type is application/x-www-form-urlencoded Provide a template name for more complex payloads.
Batching Options	Optional	✔	Record Count Maximum, between 10 and 10,000. Time To Live, in minutes, between 5 and 60 minutes.
Template Variables	Optional		See: Template Variables Guide
Templates	Optional		See: Trimou Templates Guide Each template requires a unique name Inject templates into any supported field by referencing its name enclosed in double curly braces Templates can be injected into URL, URL Parameters, Headers, Cookies or Body Data fields
* Allows you to input the field value from a custom template by enclosing its name in double curly braces. For example, if your template is named “ some-template", the content rendered can be injected into the field by referencing “ {{some-template}}”.

Usage Examples

This section provides examples of HTTP requests. A simple JSON object is used in these examples for the purpose of clarity. The actual data sent will be a full event or visitor object. We also include a single URL parameter of " param1" receiving a value of " value1" to demonstrate how additional parameters are sent.

Send Event/Visitor - GET Method

When using the GET method with the Send Event Data or Send Visitor Data actions, the data is sent as a single query string parameter named "data". The value will be a URL-encoded JSON string of the event/visitor data object. Any URL parameters configured are appended as additional query string parameters.

In this example the data is:

{
    "foo" : "bar"
}

The resulting URL-encoded JSON string is:

%7B%22foo%22%3A%22bar%22%7D

You can see that this appears in the final GET request as the following query string parameter:

data=%7B%22foo%22%3A%22bar%22%7D

GET /webhook-service?data=%7B%22foo%22%3A%22bar%22%7D&param1=value1

VERSION: HTTP/1.1
CONNECTION: close
ACCEPT-ENCODING: gzip
X-HEADER-KEY: header_value
COOKIE: cookie_key=cookie_valie,__cfduid=d63c6b0e0a23195e9a7142f314360b4e11502122913
USER-AGENT: Apache-HttpClient/4.5.1 (Java/1.8.0_111)

Send Event/Visitor - POST Method

Below are sample POST requests for the following content types: application/json and application/x-www-form-urlencoded.

Content-Type: application/json

The body data is sent as a JSON payload.

POST /webhook-service?param1=value1

VERSION: HTTP/1.1
CONNECTION: close
ACCEPT-ENCODING: gzip
X-HEADER-KEY: header_value
COOKIE: cookie_key=cookie_valie
CONTENT-TYPE: application/json; charset=UTF-8
USER-AGENT: Apache-HttpClient/4.5.1 (Java/1.8.0_111)
CONTENT-LENGTH: 13

{
    "foo": "bar"
}

Content-Type: application/x-form-urlencoded

The body data is sent as a URL-encoded JSON string using the form-data field named " data".

POST /webhook-service?param1=value1

VERSION: HTTP/1.1
CONNECTION: close
ACCEPT-ENCODING: gzip
X-HEADER-KEY: header_value
COOKIE: cookie_key=cookie_valie,__cfduid=d63c6b0e0a23195e9a7142f314360b4e11502122913
CONTENT-TYPE: application/x-www-form-urlencoded; charset=UTF-8
USER-AGENT: Apache-HttpClient/4.5.1 (Java/1.8.0_111)
CONTENT-LENGTH: 32

data=%7B%22foo%22%3A%22bar%22%7D

Vendor Use Cases

The following resources provide examples of advanced configurations using Webhook and provide a good foundation and overview of what is possible with custom requests.

• Kony API
• Keen.io API
• Salesforce Predictive Intelligence (formerly iGoDigital) API
• Facebook App Events API

FAQ

How are HTTP Response Cookies Handled?

While cookie-based session management is common in web browsers, it is generally discouraged in server-to-server environments that communicate with stateless APIs. For that reason, the Webhook connector does not track cookie-based sessions and effectively ignores Set-Cookie header values in HTTP responses.

Change Log

11-05-2020

• Added batch support for the Webhook 2-Legged OAuth2 and 3-Legged OAuth2 connectors.

12-18-2018

• Disabled Apache cookie management for Webhook connector to prevent domain-level cookies from being shared.

08-24-2017

• Added two new actions: Send Event Data via HTTP Request and Send Visitor Data via HTTP Request.
• Removed the following two Actions: POST-visitor and PUT-visitor. Though the actions are no longer displayed in the Actions drop-down list, we will continue supporting them if the actions are currently installed in your profile.

03-02-2017

• Added new Webhook OAuth2 Connector for supporting OAuth service. This service is separate from the Webhook (BasicAuth) Connector.

11-13-2016

• Added new Send Custom Request Action to support complex JSON and XML payloads. Supports a built-in template utility for translating nested JSON.
• Moved GET, POST, and PUT methods under the new Action. They are no longer treated as separate Actions

06-14-2016

• The AudienceDirect Connector has been retired in favor of Webhook.
• The POST-visitor and PUT-Visitor Actions are now integrated in the new Webhook (BasicAuth) Connector.
• If your profile contains any deprecated/non-functional AudienceDirect Actions, you must reconfigure them in a new Webhook instance.