Webhook Connector Setup Guide | Server-Side Connectors |Preview of Tealium Docs

About Webhook Connectors

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.

There are three Webhook connectors to choose from based on the authorization requirements of your vendor, as follows:

Webhook (BasicAuth) – For services that do not require authentication or only require basic authentication with a username and password.
Webhook OAuth2 (3-Legged) – Requires the user to login to the service to obtain an access token.
Webhook OAuth2 (2-Legged) – Does not require the user to login to the service. The webhook is configured with the information required to authenticate.

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 type of 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:

Title
- Required
- Enter a descriptive title for the webhook.
BasicAuth Username
- Enter the username of your webhook’s authentication.
BasicAuth Password
- Enter the password of your webhok’s authentication.

Click Next or go to the Actions tab.

Use the Actions tab to 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:

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

Click Establish Connection to test the 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:

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

Action Parameters for all Webhook Actions

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 for the header to 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 for the cookie to 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

Regarding Template Support: 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}}.

Requirements

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

Connector 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	✓	✓
Send Batched Customized Data via HTTP Request (Advanced)	Sends batched event/visitor attributes specified via mappings.	✓	✓

Configure Settings

Go to the Connector Marketplace and add a new connector. Read the Connector Overview article for general instructions on how to add a connector.

After adding the connector, configure the following settings:

Basic Authentication
- Username (Optional)
- Enter username if API endpoint requires basic authentication
Basic Authentication
- Password (Optional)
- Enter password if API endpoint requires basic authentication

Action Settings - Parameters and Options

Click Next or go to the Actions tab. This is where you configure connector actions.

This section describes how to set up parameters and options for each action.

Action - Send Event Data via HTTP Request

Parameters

Parameter	Description
Method	Required: select request method. If GET is selected, the event data is delivered as a JSON URL-encoded query string parameter with the `data` key.
URL	Required. Provide URL to submit request to. Template Support: reference template name to generate URL from template.
URL Parameters	Optional. Provide parameters to append to URL. Template Support: reference template name to generate parameter value from template.
Headers	Optional. Map HTTP header values to header names. Template Support: reference template name to generate header value from template.
Cookies	Optional. Map cookie values to cookie names. Cookies are added as single HTTP header value. For example: `Cookie: name1=value1; name2=value2` Template Support: reference template name to generate cookie value from template.
Body Content Type	Optional. Select available type or provide custom value. All types are UTF-8 encoded and added as a header. For example: `Content-Type: text/plain; charset=UTF-8` Content type is required if body data is provided.
Template Variables	Optional. Provide template variables as data input for templates. For more information, see Template Variables Guide. Name nested template variables with the dot notation. For example: `items.name` Nested template variables are typically built from data layer list attributes.
Templates	Optional. Provide templates to be referenced in either URL, URL Parameter, Header, or Body Data. For more information, see Templates Guide. Templates are injected by name with double curly braces into supported fields. For example: `{{SomeTemplateName}}` When using OAuth, the template variable `{{webhook_access_token}}` refers to the token returned by the authentication request.
Print Attribute Names	If attribute names are updated, the names in the payload reflects the update.
Redirection	Allow redirection only if the method is GET.

Action - Send Visitor Data via HTTP Request

Parameters

Parameter	Description
Method	Required Select request method. If GET is selected, the visitor data is delivered as a JSON URL-encoded query string parameter with the `data` key.
URL	Required. Provide URL to submit request to. Template Support: reference template name to generate URL from template.
URL Parameters	Optional. Provide parameters to append to URL. Template Support: reference template name to generate parameter value from template.
Headers	Optional. Map HTTP header values to header names. Template Support: reference template name to generate header value from template.
Cookies	Optional. Map cookie values to cookie names. Cookies are added as single HTTP header value. For example: `Cookie: name1=value1; name2=value2` Template Support: reference template name to generate cookie value from template.
Body Content Type	Optional. Select available type or provide custom value. All types are UTF-8 encoded and are added as a header. For example: `Content-Type: text/plain; charset=UTF-8` Content type is required if body data is provided.
Template Variables	Optional. Provide template variables as data input for templates. For more information, see Template Variables Guide. Name nested template variables with the dot notation. For example: `items.name` Nested template variables are typically built from data layer list attributes.
Templates	Optional. Provide templates to be referenced in either URL, URL Parameter, Header, or Body Data. For more information, see Templates Guide. Templates are injected by name with double curly braces into supported fields. For example: `{{SomeTemplateName}}` When using OAuth, the template variable `{{webhook_access_token}}` refers to the token returned by the authentication request.
Include Current Visit Data	Check this box if you want to include current visit data.
Print Attribute Names	If attribute names are updated, the names in the payload reflect the update.
Redirection	Allow redirection only if the method is GET.

Action - Send Customized Data via HTTP Request (Advanced)

Parameters

Parameter	Description
Method	Required. For more information, see Webhook Send Custom Request Guide. Select request method.
URL	Required. Provide URL to submit request to. Template Support: reference template name to generate URL from template.
URL Parameters	Optional. Provide parameters to append to URL. Template Support: reference template name to generate parameter value from template.
Headers	Optional. Map HTTP header values to header names. Template Support: reference template name to generate header value from template.
Cookies	Optional. Map cookie values to cookie names. Cookies are added as single HTTP header value. For example: `Cookie: name1=value1; name2=value2` Template Support: reference template name to generate cookie value from template.
Body Content Type	Optional. Select available type or provide custom value. All types are UTF-8 encoded and are added as a header. For example: `Content-Type: text/plain; charset=UTF-8` Content type is required if body data is provided.
Body Data	Optional. Provide data to construct message body. Template Support: reference template name to generate body data from template. Map values to names if body content type is `multipart/form-data` or `application/x-www-form-urlencoded`, otherwise reference template name and select only the Body option.
Template Variables	Optional. Provide template variables as data input for templates. For more information, see Template Variables Guide. Name nested template variables with the dot notation. For example: `items.name` Nested template variables are typically built from data layer list attributes.
Templates	Optional. Provide templates to be referenced in either URL, URL Parameter, Header. or Body Data. For more information, see Templates Guide. Templates are injected by name with double curly braces into supported fields. For example: `{{SomeTemplateName}}` When using OAuth, the template variable `{{webhook_access_token}}` refers to the token returned by the authentication request.

Action - Send Batched Customized Data via HTTP Request (Advanced)

Batch Limits

This action uses batched requests to support high-volume data transfers to the vendor. For more information, see Batched Actions. Requests are queued until one of the following thresholds is met or the profile is published:

Maximum number of requests: 100
Maximum time since oldest request: 60 minutes
Maximum size of requests: 16 MB

Parameters

Parameter	Description
Method	Required. For more information see Webhook Send Custom Request Guide. Select request method.
URL	Required. Provide URL to submit request to. Template Support: reference template name to generate URL from template.
Body Content Type	Optional. Select available type or provide custom value. All types are UTF-8 encoded and are added as a header. For example: `Content-Type: text/plain; charset=UTF-8` Content type is required if body data is provided.
Body Data	Optional. Provide data to construct message body. Template Support: reference template name to generate body data from template. Map values to names if body content type is `multipart/form-data` or `application/x-www-form-urlencoded`, otherwise reference a template name and select only the `Body` option.
Suffix	A non-repeating portion of the request that follows Body Data. For more information, see Webhook - Using the Send Customized Data Via HTTP Request Action (Advanced) .
Prefix	A non-repeating portion of the request that precedes Body Data. For more information, see Webhook - Using the Send Customized Data Via HTTP Request Action (Advanced) .
Joiner	A character or string that separates individual data items in Body Data. For more information, see Webhook - Using the Send Customized Data Via HTTP Request Action (Advanced) .
Record Count Maximum	Maximum record count.
Time To Live (minutes)	Time to live, in minutes.
URL Parameters	Optional. Provide parameters to append to URL. Template Support: reference template name to generate parameter value from template.
Headers	Optional. Map HTTP header values to header names. Template Support: reference template name to generate header value from template.
Cookies	Optional. Map cookie values to cookie names. Cookies are added as single HTTP header value. For example: `Cookie: name1=value1; name2=value2` Template Support: reference template name to generate cookie value from template.
Template Variables	Optional. Provide template variables as data input for templates. For more information, see Template Variables Guide. Name nested template variables with the dot notation. For example: `items.name` Nested template variables are typically built from data layer list attributes.
Templates	Optional. Provide templates to be referenced in either URL, URL Parameter, Header, or Body Data. For more information, see Templates Guide. Templates are injected by name with double curly braces into supported fields. For example: `{{SomeTemplateName}}` When using OAuth, the template variable `{{webhook_access_token}}`refers to the token returned by the authentication request.

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_mainst": 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 includes all of the applicable Visitor attributes for that visitor. The data object is organized by attribute type. If an attribute is not assigned it does 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
    }
}

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 is 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 is 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

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

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 Webhook configurations and provide a good foundation and overview of what is possible with custom requests.

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-30-2021

Added configuration option for Webhook connectors to support 302 responses when configured.

07-20-2021

In the Connector Actions table, added links to each action.

06-07-2021

Added Action - Send Batched Customized Data via HTTP Request (Advanced) action and Batch Limitations section

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, Tealium continues to support 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.