Webhookコネクタ構成ガイド
この記事では、Webhookコネクタの構成方法について説明します。
Webhookコネクタについて
Webhookコネクタを使用すると、カスタマイズされたHTTPリクエストを使用してデータをベンダーに送信し、HTTPリクエストのすべての側面（URL、URLパラメータ、ヘッダ、クッキー、ボディコンテンツタイプ、ボディデータ）を制御できます。Webhookは、バッチ処理と複雑で動的なデータ形式を処理するために設計された強力なテンプレート機能もサポートしています。
ベンダーの認証要件に基づいて、以下の4つのWebhookコネクタから選択できます：
- Webhook (BasicAuth) – 認証が不要なサービス、またはユーザー名とパスワードで基本認証が必要なサービス向け。
- Webhook OAuth2 (3-Legged) – ユーザーがサービスにログインしてアクセストークンを取得する必要があります。
- Webhook OAuth2 (2-Legged) – ユーザーがサービスにログインする必要はありません。Webhookは認証に必要な情報で構成されます。
- Webhook JWT – JSONウェブトークン認証を使用します。ユーザーがサービスにログインする必要はありません。Webhookは認証に必要な情報で構成されます。
Webhook OAuth2は、明示的にOAuth 2.0認証を必要とするサービスに使用されます。
始めるには、コネクタマーケットプレイスに移動し、使用したいWebhookインスタンスを追加します。コネクタの追加方法の一般的な指示については、Connector Overviewを参照してください。
以下のセクションでは、各タイプのWebhookコネクタの構成構成を順を追って説明します。
Webhook (BasicAuth) 構成
このWebhookは、HTTPヘッダフィールドのAuthorizationを使用して基本的なHTTP認証をサポートします。資格情報は、{username}:{password}のBase64エンコードされた文字列として渡されます。
BasicAuth Webhook構成のための以下の構成構成を使用します：
- タイトル
- 必須
- Webhookの詳細なタイトルを入力します。
- BasicAuthユーザー名
- Webhookの認証のユーザー名を入力します。
- BasicAuthパスワード
- Webhookの認証のパスワードを入力します。
- JWT 認証
- JSONウェブトークンを入力します。
次へをクリックするか、アクションタブに移動します。
- アクションタブを使用して、トリガーするHTTPリクエストを構成します。
Webhook OAuth2 (3-Legged) 構成
WebhookのOAuth実装は、サーバーサイドアプリケーションのみをサポートします。
OAuth 2.0サービスでウェブアプリケーションを登録することを忘れないでください。アプリケーションは、次のリダイレクトURLを許可するように構成する必要があります：https://my.tealiumiq.com/oauth/webhook/callback.html
OAuth2 (3-legged) Webhook構成のための以下の構成構成を使用します：
- クライアントID
- 必須。
- OAuthサービスからアプリケーションに割り当てられたクライアント識別子を入力します。
- クライアントシークレット
- 必須。
- OAuthサービスからアプリケーションに割り当てられたクライアントシークレットを入力します。
- スコープ
- アプリケーションへのアクセスを要求する許可のタイプを選択します。
- 認証URL
- 必須。
- ユーザーを認証後にリダイレクトしたいURLを入力します。
- 認証URLクエリパラメータ
- 認証URLの1つ以上の名前-値ペアを選択します。
- 複数のペアはアンパサンド(
&)で区切ります。 - 先頭にアンパサンド(
&)を使用しないでください。- 正しい：
access_type=offline&prompt=consent - 不正確：
&access_type=offline&prompt=consent
- 正しい：
- アクセストークンURL
- 必須。
- リフレッシュトークンを取得するためのトークンURLを入力します。
接続を確立をクリックして接続をテストします。
Webhook OAuth2 (2-Legged) 構成
TealiumのWebhook OAuth2コネクタを使用すると、OAuth2 Two-Legged認証を必要とし、クライアント資格情報とリソース所有者パスワード資格情報の付与をサポートするAPIに対して、完全にカスタマイズされたデータをHTTPリクエストとして送信できます。
コネクタを追加した後、以下の構成構成を使用してOAuth2 2-Legged Webhook構成を行います：
- アクセストークンURL
- 必須。
- アクセストークンをリクエストするためのAPIエンドポイントURLを入力します。
- クライアントID
- 必須。
- ウェブアプリケーションのクライアントIDを入力します。
- クライアントシークレット
- 必須。
- ウェブアプリケーションのクライアントシークレットを入力します。
- ユーザー名
- ユーザー名を入力します。
- パスワード付与タイプを使用する場合は、ユーザー名が必要です。
- パスワード
- パスワードを入力します。
- パスワード付与タイプを使用する場合は、パスワードが必要です。
- スコープ
- リクエストする権限の範囲を選択します（一部のOAuth2サービスのみ必要）。
- 追加の認証パラメータ
- 追加の認証パラメータを追加します（一部のOAuth2サービスのみ必要）。
- 複数のパラメータは
&で区切ります。
- 認証トークンの位置
- 認証トークンを配置する場所を指定します。
- 認証ヘッダプレフィックス
- デフォルト値は
Bearerです。 - 新しい値を指定して上書きします（一部のOAuth2サービスのみ必要）。
- デフォルト値は
すべての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リクエスト経由でバッチ化されたカスタマイズデータを送信（アドバンス） | マッピングを通じて指定されたバッチ化されたイベント/訪問属性を送信します。 | ✓ | ✓ |
構成の構成
コネクタマーケットプレイスに移動し、新しいコネクタを追加します。コネクタを追加する一般的な手順については、コネクタ概要の記事を参照してください。
コネクタを追加した後、以下の構成を構成します：
-
基本認証
- ユーザー名（任意）
- APIエンドポイントが基本認証を必要とする場合は、ユーザー名を入力します
-
基本認証
- パスワード（任意）
- APIエンドポイントが基本認証を必要とする場合は、パスワードを入力します
アクション構成 - パラメータとオプション
次へをクリックするか、アクションタブに移動します。ここでコネクタアクションを構成します。
このセクションでは、各アクションのパラメータとオプションの構成方法について説明します。
アクション - HTTPリクエスト経由でイベントデータを送信
パラメータ
| パラメータ | 説明 |
|---|---|
| メソッド |
|
| URL |
|
| URLパラメータ |
|
| ヘッダー |
|
| クッキー |
|
| ボディコンテンツタイプ |
|
| テンプレート変数 |
|
| テンプレート |
|
| 属性名の印刷 |
|
| リダイレクション |
|
アクション - HTTPリクエスト経由で訪問データを送信
パラメータ
| パラメータ | 説明 |
|---|---|
| メソッド |
|
| URL |
|
| URLパラメータ |
|
| ヘッダー |
|
| クッキー |
|
| ボディコンテンツタイプ |
|
| テンプレート変数 |
|
| テンプレート |
|
| 現在の訪問データを含める |
|
| 属性名を印刷 |
|
| リダイレクション |
|
アクション - HTTPリクエストを介してカスタマイズされたデータを送信（アドバンス）
パラメータ
| パラメータ | 説明 |
|---|---|
| メソッド |
|
| URL |
|
| URLパラメータ |
|
| ヘッダー |
|
| クッキー |
|
| ボディコンテンツタイプ |
|
| ボディデータ |
|
| テンプレート変数 |
|
| テンプレート |
|
アクション - HTTPリクエストを介してバッチ化されたカスタマイズデータを送信（アドバンス）
バッチ制限
このアクションは、バッチリクエストを使用して、ベンダーへの大量のデータ転送をサポートします。詳細はBatched Actionsを参照してください。リクエストは、以下のいずれかの閾値が達成されるか、プロファイルが公開されるまでキューに入れられます：
- リクエストの最大数：100
- 最も古いリクエストからの最大時間：60分
- リクエストの最大サイズ：16MB
パラメータ
| パラメータ | 説明 |
|---|---|
| メソッド |
|
| URL |
|
| ボディコンテンツタイプ |
|
| ボディデータ |
|
| Suffix |
|
| Prefix |
|
| Joiner |
|
| Record Count Maximum |
|
| Time To Live (minutes) |
|
| URL Parameters |
|
| Headers |
|
| Cookies |
|
| Template Variables |
|
| Templates |
|
イベントデータ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": {
"訪問開始": 1500999541000,
"last_event_ts": 1500999541000
},
"properties": {
"アクティブなブラウザタイプ": "Chrome",
"アクティブなオペレーティングシステム": "MacOS",
"アクティブなブラウザバージョン": "53",
"アクティブなプラットフォーム": "browser",
"アクティブなデバイス": "other"
},
"flags": {
"直接訪問": true
},
"property_sets": {
"アクティブなデバイス": [
"other"
],
"アクティブなブラウザバージョン": [
"53"
],
"アクティブなオペレーティングシステム": [
"MacOS"
],
"アクティブなプラットフォーム": [
"browser"
],
"アクティブなブラウザタイプ": [
"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メソッド
イベントデータの送信または訪問データの送信のアクションで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
バージョン: HTTP/1.1
接続: close
受け入れエンコーディング: gzip
X-ヘッダーキー: header_value
クッキー: cookie_key=cookie_valie,cfduid=d63c6b0e0a23195e9a7142f314360b4e11502122913
ユーザーエージェント: 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
バージョン: HTTP/1.1
接続: close
受け入れエンコーディング: gzip
X-ヘッダーキー: header_value
クッキー: cookie_key=cookie_valie
コンテンツタイプ: application/json; charset=UTF-8
ユーザーエージェント: Apache-HttpClient/4.5.1 (Java/1.8.0_111)
コンテンツ長: 13
{
"foo": "bar"
}
Content-Type: application/x-form-urlencoded
本文データは、dataという名前のフォームデータフィールドを使用してURLエンコードされたJSON文字列として送信されます。
POST /webhook-service?param1=value1
バージョン: HTTP/1.1
接続: close
受け入れエンコーディング: gzip
X-ヘッダーキー: header_value
クッキー: cookie_key=cookie_valie,cfduid=d63c6b0e0a23195e9a7142f314360b4e11502122913
コンテンツタイプ: application/x-www-form-urlencoded; charset=UTF-8
ユーザーエージェント: Apache-HttpClient/4.5.1 (Java/1.8.0_111)
コンテンツ長: 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ヘッダー値を効果的に無視します。
変更ログ
2021年11月30日
- Webhookコネクタの構成オプションを追加し、構成時に302レスポンスをサポートします。
2021年7月20日
- コネクタアクションテーブルに、各アクションへのリンクを追加しました。
2021年6月7日
- アクション - HTTPリクエストを介したバッチ化されたカスタマイズデータの送信（アドバンスド）アクションとバッチ制限セクションを追加しました。
2020年11月5日
- Webhook 2-Legged OAuth2と3-Legged OAuth2コネクタにバッチサポートを追加しました。
2018年12月18日
- WebhookコネクタのApacheクッキー管理を無効化し、ドメインレベルのクッキーが共有されるのを防ぎました。
2017年8月24日
- 新しいアクションを追加しました：HTTPリクエストを介したイベントデータの送信と訪問データの送信。
- 次の2つのアクションを削除しました：POST-visitorとPUT-visitor。これらのアクションはアクションのドロップダウンリストには表示されなくなりましたが、Tealiumは現在プロファイルにインストールされているアクションを引き続きサポートします。
2017年3月2日
- OAuthサービスをサポートするための新しいWebhook OAuth2コネクタを追加しました。このサービスはWebhook（BasicAuth）コネクタとは別です。
2016年11月13日
- 複雑なJSONとXMLペイロードをサポートするための新しいSend Custom Requestアクションを追加しました。ネストされたJSONを翻訳するための組み込みテンプレートユーティリティをサポートします。
- GET、POST、PUTメソッドを新しいアクションの下に移動しました。これらはもはや別々のアクションとして扱われません。
2016年6月14日
- AudienceDirectコネクタはWebhookに置き換えられました。
- POST-visitorとPUT-Visitorアクションは新しいWebhook（BasicAuth）コネクタに統合されました。
- プロファイルに非機能/非推奨のAudienceDirectアクションが含まれている場合、新しいWebhookインスタンスでそれらを再構成する必要があります。
最終更新日 :: 2022年June月23日