- TLC Home Home
- Discussions & Ideas Discussions & Ideas
- Product Guides Product Guides
- Knowledge Base Knowledge Base
- Developer Docs Developer Docs
- Education Education
- Blog TLC Blog
- Support Desk Support Desk
This article describes how to set up the Webhook Connector.
In this article:
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.
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 | ✓ | ✓ |
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" }
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 } }
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.
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:
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:
&
".
&
" at the start.
access_type=offline&prompt=consent
&access_type=offline&prompt=consent
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:
&
The following parameters are available to all Webhook Actions.
Input Field |
Required/ Optional |
Template Support* | Notes |
---|---|---|---|
Method | Required |
Supports the following methods:
|
|
URL | Required | ✔ |
|
URL Parameters | Optional | ✔ |
|
Headers |
Optional for Webhook (BasicAuth) Required for Webhook OAuth2 |
✔ |
|
Cookies | Optional | ✔ |
|
Body Content Type | Optional |
|
|
Body Data | Optional | ✔ |
|
Batching Options | Optional | ✔ |
|
Template Variables | Optional | ||
Templates | Optional |
|
|
* 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}} ”. |
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.
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¶m1=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)
Below are sample POST requests for the following content types: application/json
and application/x-www-form-urlencoded
.
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" }
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
The following resources provide examples of advanced configurations using Webhook and provide a good foundation and overview of what is possible with custom requests.
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.
Copyright All Rights Reserved © 2008-2021