Webhookコネクタ構成ガイド
この記事では、Webhookコネクタの構成方法について説明します。
Webhookコネクタについて
Webhookコネクタを使用すると、カスタマイズされたHTTPリクエストを使用してデータをベンダーに送信し、URL、URLパラメータ、ヘッダー、クッキー、ボディコンテンツタイプ、ボディデータなど、HTTPリクエストのすべての側面を構成できます。Webhookはバッチ処理と、複雑で動的なデータ形式を処理するために設計された強力なテンプレート機能もサポートしています。
ベンダーの認証要件に基づいて選択できるWebhookコネクタは4種類あります：
- Webhook (BasicAuth)：認証が不要、またはユーザー名とパスワードのみの基本認証が必要なサービス用。
- Webhook OAuth2 (3-Legged)：ユーザーがサービスにログインしてアクセストークンを取得する必要があります。
- Webhook OAuth2 (2-Legged)：ユーザーのサービスへのログインが不要です。Webhookは認証に必要な情報で構成されます。
- Webhook JWT：JSON Webトークン認証を使用します。ユーザーのサービスへのログインが不要です。Webhookは認証に必要な情報で構成されます。
Webhook OAuth2は、OAuth 2.0認証を明示的に要求するサービスに使用されます。
始めるには、コネクタマーケットプレイスにアクセスし、使用したいWebhookインスタンスを追加します。コネクタの追加方法についての一般的な指示については、コネクタ概要を参照してください。
以下のセクションでは、各タイプのWebhookコネクタの構成について説明します。
Webhook (BasicAuth) 構成
このWebhookは、HTTPヘッダーフィールド Authorization を使用して基本HTTP認証をサポートします。認証情報は {username}:{password} のBase64エンコードされた文字列として渡されます。
BasicAuth Webhook構成のための以下の構成を使用してください：
- 名前
- 必須
- Webhookの説明的なタイトルを入力します。
- BasicAuth ユーザー名
- Webhookの認証用ユーザー名を入力します。
- BasicAuth パスワード
- Webhookの認証用パスワードを入力します。
次へをクリックするか、アクションタブに進みます。
- HTTPリクエストをトリガーするためにアクションタブを使用します。
Webhook OAuth2 (3-Legged) 構成
このWebhookのOAuth実装はサーバーサイドアプリケーションのみをサポートします。
OAuth 2.0サービスにWebアプリケーションを登録することを忘れないでください。アプリケーションはリダイレクトURLを許可するように構成する必要があります：https://my.tealiumiq.com/oauth/webhook/callback.html
OAuth2 (3-legged) Webhook構成のための以下の構成を使用してください：
- 名前
- (必須) Webhookの説明的なタイトルを入力します。
- クライアントID
- (必須) OAuthサービスから割り当てられたアプリケーションのクライアント識別子を入力します。
- クライアントシークレット
- (必須) OAuthサービスから割り当てられたアプリケーションのクライアントシークレットを入力します。
- スコープ
- アプリケーションへのアクセス許可のタイプを選択します。
- 認証URL
- (必須) ユーザーを認証後にリダイレクトするURLを入力します。
- 認証URLクエリパラメータ
- 認証URLのための1つ以上の名前-値ペアを選択します。
- 複数のペアをアンパサンド (
&) を使用して区切ります。 - アンパサンド (
&) を先頭に使用しないでください。- 正しい:
access_type=offline&prompt=consent - 誤り:
&access_type=offline&prompt=consent
- 正しい:
- アクセストークンURL
- (必須) リフレッシュトークンを取得するためのトークンURLを入力します。
- 認証トークンの位置
- 認証トークンを配置する場所を指定します。
- 認証ヘッダープレフィックス
- デフォルト値は
Bearerです。 - 新しい値を指定して上書きします（一部のOAuth2サービスで必要です）。
- デフォルト値は
接続を確立をクリックして接続をテストします。
Webhook OAuth2 (2-Legged) 構成
TealiumのWebhook OAuth2コネクタは、OAuth2 Two-Legged認証を必要とするAPIに完全にカスタマイズされたデータをHTTPリクエストとして送信することができます。これはクライアント資格情報とリソース所有者パスワード資格情報の付与をサポートします。
コネクタを追加した後、OAuth2 2-Legged Webhook構成のための以下の構成を使用してください：
- 名前
- (必須) Webhookの説明的なタイトルを入力します。
- アクセストークンURL
- (必須) アクセストークンを要求するAPIエンドポイントURLを入力します。
- クライアントID
- WebアプリケーションのクライアントIDを入力します。
- クライアントIDは、クライアント資格情報の付与タイプを使用する場合に必要です。
- クライアントシークレット
- Webアプリケーションのクライアントシークレットを入力します。
- クライアントシークレットは、クライアント資格情報の付与タイプを使用する場合に必要です。
- ユーザー名
- ユーザー名を入力します。
- ユーザー名は、パスワードの付与タイプを使用する場合に必要です。
- トークンエンドポイントが基本認証ヘッダーも必要とする場合は、クライアント認証IDとクライアント認証シークレットを入力します。
- パスワード
- パスワードを入力します。
- パスワードは、パスワードの付与タイプを使用する場合に必要です。
- クライアント認証ID
- 認証ヘッダーの一部として送信するクライアントIDです。
- クライアント認証シークレット
- 認証ヘッダーの一部として送信するクライアントシークレットです。
- スコープ
- 要求する権限の範囲を選択します（一部のOAuth2サービスで必要です）。
- 追加の認証パラメータ
- 追加の認証パラメータを追加します（一部のOAuth2サービスで必要です）。
- 複数のパラメータを
&で区切ります。
- 認証URL
- (必須) 認証コードを要求するAPIエンドポイントURLを入力します。
- 認証トークンの位置
- 認証トークンを配置する場所を指定します。
- 認証ヘッダープレフィックス
- デフォルト値は
Bearerです。 - 新しい値を指定して上書きします（一部のOAuth2サービスで必要です）。
- デフォルト値は
Webhook (JWT) 構成
このWebhookは、JSON Webトークン（JWT）を使用して認証をサポートします。
Webhook (JWT)構成のための以下の構成を使用してください：
- 名前
- 必須
- Webhookの説明的なタイトルを入力します。
- JWTトークン
- JSON Webトークンを入力します。
次へをクリックするか、アクションタブに進みます。
- HTTPリクエストをトリガーするためにアクションタブを使用します。
すべてのWebhookアクションのアクションパラメータ
以下のパラメータは、すべてのWebhookアクションで利用可能です。
| 入力フィールド | 必須/任意 | テンプレートサポート | 備考 |
|---|---|---|---|
| メソッド | 必須 | 次のメソッドをサポート:
|
|
| URL | 必須 | ✔ |
|
| URLパラメータ | 任意 | ✔ |
|
| ヘッダー | Webhook（BasicAuth）では任意、Webhook OAuth2では必須 | ✔ |
|
| クッキー | 任意 | ✔ |
|
| ボディコンテンツタイプ | 任意 |
|
|
| ボディデータ | 任意 | ✔ |
|
| バッチングオプション | 任意 | ✔ |
|
| テンプレート変数 | 任意 |
|
|
| テンプレート | 任意 |
|
テンプレートサポートについて: カスタムテンプレートからフィールド値を入力することができます。たとえば、テンプレートが some-template という名前の場合、その内容は {{some-template}} を参照することでフィールドに注入されます。
要件
- EventStream用に有効化されたTealiumアカウント（イベントデータ用）
- AudienceStream用に有効化されたTealiumアカウント（訪問データ用）
コネクタアクション
| アクション名 | 説明 | Webhook (BasicAuth) | Webhook OAuth2 |
|---|---|---|---|
| HTTPリクエストを介してイベントデータを送信 | イベントオブジェクト全体を、URLエンコードされたJSON文字列またはJSONペイロードとして送信します。 | ✓ | ✓ |
| HTTPリクエストを介して訪問データを送信 | 訪問プロファイルオブジェクト全体を、URLエンコードされたJSON文字列またはJSONペイロードとして送信します。 | ✓ | ✓ |
| HTTPリクエストを介してカスタマイズされたデータを送信（高度） | マッピングを介して指定された個々のイベント/訪問属性を送信します。 | ✓ | ✓ |
| HTTPリクエストを介してバッチ処理されたカスタマイズデータを送信（高度） | マッピングを介して指定されたバッチ処理されたイベント/訪問属性を送信します。 | ✓ | ✓ |
| HTTPリクエストを介してバッチ処理された訪問データを送信 | イベントオブジェクト全体を、URLエンコードされたJSON文字列またはJSONペイロードとして送信します。 | ✓ | ✓ |
構成の構成
コネクターマーケットプレイスにアクセスして新しいコネクターを追加してください。コネクターを追加する一般的な手順については、コネクター概要の記事を参照してください。
コネクターを追加した後、以下の構成を構成します：
-
基本認証
- ユーザー名（オプション）
- APIエンドポイントが基本認証を要求する場合はユーザー名を入力
-
基本認証
- パスワード（オプション）
- APIエンドポイントが基本認証を要求する場合はパスワードを入力
アクション構成 - パラメータとオプション
次へをクリックするか、アクションタブに進みます。ここでコネクタアクションを構成します。
このセクションでは、各アクションのパラメータとオプションの構成方法について説明します。
アクション - HTTPリクエストを介してイベントデータを送信
パラメータ
| パラメータ | 説明 |
|---|---|
| メソッド |
|
| URL |
|
| URLパラメータ |
|
| ヘッダー |
|
| クッキー |
|
| ボディコンテンツタイプ |
|
| テンプレート変数 |
|
| テンプレート |
|
| 属性名の印刷 |
|
| リダイレクション |
|
アクション - HTTPリクエストを介して訪問データを送信
パラメータ
| パラメータ | 説明 |
|---|---|
| 現在の訪問データを訪問データに含める |
|
| 現在の訪問イベントデータを除外 |
|
| 属性名の印刷 |
|
| リダイレクション |
|
アクション - HTTPリクエストを介してカスタマイズされたデータを送信（高度）
パラメータ
| パラメータ | 説明 |
|---|---|
| メソッド |
|
| URL |
|
| URLパラメータ |
|
| ヘッダー |
|
| クッキー |
|
| ボディコンテンツタイプ |
|
| ボディデータ |
|
| テンプレート変数 |
|
| テンプレート |
|
アクション - HTTPリクエストを介してバッチデータを送信
バッチ制限
このアクションは、ベンダーへの大量データ転送をサポートするためにバッチリクエストを使用します。詳細はバッチアクションを参照してください。リクエストは、次のいずれかの閾値が満たされるか、プロファイルが公開されるまでキューに入れられます：
- 最大リクエスト数：100
- 最古のリクエストからの最大時間：60分
- リクエストの最大サイズ：16 MB
パラメータ
| パラメータ | 説明 |
|---|---|
| メソッド |
|
| URL |
|
| ボディコンテンツタイプ |
|
| ボディデータ |
|
| レコード数の最大値 |
|
| 生存時間 (分) |
|
| URLパラメータ |
|
| ヘッダー |
|
| クッキー |
|
| テンプレート変数 |
|
| テンプレート |
|
| 現在の訪問データを含む |
|
| 属性名を印刷 |
|
| リダイレクション |
|
アクション - HTTPリクエストを介してバッチカスタマイズデータを送信 (高度)
バッチ制限
このアクションは、ベンダーへの大量データ転送をサポートするためにバッチリクエストを使用します。詳細はバッチアクションを参照してください。リクエストは、次のいずれかの閾値に達するか、プロファイルが公開されるまでキューに入れられます：
- リクエストの最大数：100
- 最も古いリクエストからの最大時間：60分
- リクエストの最大サイズ：16 MB
パラメータ
| パラメータ | 説明 |
|---|---|
| メソッド |
|
| URL |
|
| ボディコンテンツタイプ |
|
| ボディデータ |
|
| サフィックス |
|
| プレフィックス |
|
| ジョイナー |
|
| URLパラメータ |
|
| ヘッダー |
|
| クッキー |
|
| テンプレート変数 |
|
| テンプレート |
|
イベントデータJSON
イベントに含まれる予想されるJSONペイロードには、イベントの標準属性すべてと、イベントを送信したプラットフォーム固有の追加属性が含まれます。例えば、ウェブサイトから受け取ったイベントにはDOMやクッキーの属性が含まれ、モバイルデバイスから受け取ったイベントにはデバイスやキャリアの属性が含まれます。
イベントデータJSONオブジェクトの形式例：
{
"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"
}
訪問データJSON
訪問に関する予想されるJSONペイロードには、その訪問に適用可能なすべての訪問属性が含まれます。データオブジェクトは属性タイプごとに整理されています。属性が割り当てられていない場合、訪問オブジェクトには表示されません。現在の訪問のデータも current_visit キーの下に含まれます。
訪問データJSONオブジェクトの形式例：
{
"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
}
}
使用例
このセクションでは、HTTPリクエストの例を提供します。これらの例では明確さのために単純なJSONオブジェクトが使用されています。実際に送信されるデータは完全なイベントまたは訪問オブジェクトです。また、追加のパラメータがどのように送信されるかを示すために、param1 が value1 の値を受け取る単一のURLパラメータも含まれています。
イベント/訪問の送信 - GETメソッド
Send Event DataまたはSend Visitor Dataアクションを使用する場合、GETメソッドではデータが data という名前の単一のクエリ文字列パラメータとして送信されます。値はイベント/訪問データオブジェクトのURLエンコードされたJSON文字列です。構成されたURLパラメータは追加のクエリ文字列パラメータとして追加されます。
この例では、データは次のとおりです：
{
"foo" : "bar"
}
結果のURLエンコードされたJSON文字列は次のとおりです：
%7B%22foo%22%3A%22bar%22%7D
これは最終的なGETリクエストで次のクエリ文字列パラメータとして表示されます：
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)
イベント/訪問の送信 - POSTメソッド
次に、application/json および application/x-www-form-urlencoded コンテンツタイプのPOSTリクエストのサンプルを示します。
Content-Type: application/json
本文データはJSONペイロードとして送信されます。
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
本文データは data という名前のフォームデータフィールドを使用してURLエンコードされたJSON文字列として送信されます。
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
ベンダー使用例
次のリソースは、高度なWebhook構成の例を提供し、カスタムリクエストで何が可能かの良い基盤と概要を提供します。
- Kony API
- Keen.io API
- Salesforce Predictive Intelligence (formerly iGoDigital) API
- Facebook App Events API
FAQ
HTTPレスポンスクッキーはどのように扱われますか？
クッキーベースのセッション管理はウェブブラウザでは一般的ですが、ステートレスAPIと通信するサーバー間環境では一般的に推奨されません。そのため、Webhookコネクタはクッキーベースのセッションを追跡せず、HTTPレスポンスの Set-Cookie ヘッダー値を効果的に無視します。
変更履歴
2024年7月10日
- すべてのEventStream WebhookにHTTPリクエストを介してイベントデータを送信するアクションを追加しました。
- すべてのAudienceStream WebhookにHTTPリクエストを介して訪問データを送信するアクションと訪問データをバッチで送信するアクションを追加しました。
2021年11月30日
- 302レスポンスをサポートするためのWebhookコネクタの構成オプションを追加しました。
2021年7月20日
- コネクタアクションテーブルに各アクションへのリンクを追加しました。
2021年6月7日
- HTTPリクエストを介してカスタマイズされたバッチデータを送信するアクション（高度）とバッチ制限セクションを追加しました。
2020年11月5日
- Webhook 2-Legged OAuth2および3-Legged OAuth2コネクタのバッチサポートを追加しました。
2018年12月18日
- WebhookコネクタのApacheクッキー管理を無効にし、ドメインレベルのクッキーが共有されるのを防ぎました。
2017年08月24日
- 新たに2つのアクションを追加：HTTPリクエストを介してイベントデータを送信、HTTPリクエストを介して訪問データを送信。
- 以下の2つのアクションを削除：POST-visitorおよびPUT-visitor。これらのアクションはアクションドロップダウンリストには表示されなくなりましたが、プロファイルに現在インストールされている場合はTealiumが引き続きサポートします。
2017年03月02日
- OAuthサービスをサポートするための新しいWebhook OAuth2コネクタを追加。このサービスはWebhook（BasicAuth）コネクタとは別です。
2016年11月13日
- 複雑なJSONおよびXMLペイロードをサポートする新しいカスタムリクエスト送信アクションを追加。ネストされたJSONを翻訳するための組み込みテンプレートユーティリティをサポート。
- GET、POST、およびPUTメソッドを新しいアクションの下に移動。これらはもはや別のアクションとして扱われません。
2016年06月14日
- AudienceDirectコネクタはWebhookに置き換えられて廃止されました。
- POST-visitorおよびPUT-Visitorアクションは新しいWebhook（BasicAuth）コネクタに統合されました。
- プロファイルに非機能的なAudienceDirectアクションが含まれている場合は、新しいWebhookインスタンスで再構成する必要があります。
最終更新日 :: 2025年September月11日