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サービスでウェブアプリケーションを登録することを忘れないでください。アプリケーションはリダイレクト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
- クライアント資格情報の付与タイプを使用する場合に必要な、ウェブアプリケーションのクライアントIDを入力してください。
- クライアントシークレット
- クライアント資格情報の付与タイプを使用する場合に必要な、ウェブアプリケーションのクライアントシークレットを入力してください。
- ユーザー名
- パスワード付与タイプを使用する場合に必要な、あなたのユーザー名を入力してください。
- トークンエンドポイントが基本認証ヘッダーも必要とする場合は、クライアント認証IDとクライアント認証シークレットを入力してください。
- パスワード
- パスワード付与タイプを使用する場合に必要な、あなたのパスワードを入力してください。
- クライアント認証ID
- 認証ヘッダーの一部として送信するクライアントID。
- クライアント認証シークレット
- 認証ヘッダーの一部として送信するクライアントシークレット。
- スコープ
- 要求する権限の範囲を選択してください（一部のOAuth2サービスで必要です）。
- 追加の認証パラメータ
- 追加の認証パラメータを追加してください（一部のOAuth2サービスで必要です）。
- 複数のパラメータを
&で区切ってください。
- 認証URL
- 必須
- 認証コードを要求するためのAPIエンドポイントURLを入力してください。
- 認証トークンの位置
- 認証トークンを配置する場所を指定してください。
- 認証ヘッダープレフィックス
- デフォルト値は
Bearerです。 - 新しい値を指定して上書きする（一部のOAuth2サービスで必要です）。
- デフォルト値は
Webhook（JWT）構成
このWebhookは、JSONウェブトークン（JWT）を使用して認証をサポートしています。
Webhook（JWT）構成のための以下の構成を使用してください：
- 名前
- 必須
- Webhookの説明的なタイトルを入力してください。
- JWTトークン
- JSONウェブトークンを入力してください。
次へをクリックするか、アクションタブに進んでください。
- アクションタブを使用して、トリガーする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リクエストを介して訪問データを送信
パラメータ
| パラメータ | 説明 |
|---|---|
| メソッド |
|
| URL |
|
| URLパラメータ |
|
| ヘッダー |
|
| クッキー |
|
| ボディコンテンツタイプ |
|
| テンプレート変数 |
|
| テンプレート |
|
| 現在の訪問データを含む |
|
| 属性名の印刷 |
|
| リダイレクション |
|
アクション - 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オブジェクトが使用されています。実際に送信されるデータは完全なイベントまたは訪問オブジェクトです。また、追加パラメータがどのように送信されるかを示すために、単一のURLパラメータparam1がvalue1の値を受け取る例も含まれています。
イベント/ビジター送信 - 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
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構成の例を提供し、カスタムリクエストで何が可能かの良い基盤と概要を提供します。
FAQ
HTTPレスポンスクッキーはどのように扱われますか？
クッキーベースのセッション管理はウェブブラウザでは一般的ですが、ステートレスAPIと通信するサーバー間環境では一般的に推奨されません。そのため、Webhookコネクタはクッキーベースのセッションを追跡せず、HTTPレスポンスのSet-Cookieヘッダー値を効果的に無視します。
変更履歴
2024-07-10
- すべてのEventStream WebhookにHTTPリクエストを介してイベントデータを送信するアクションを追加しました。
- すべてのAudienceStream WebhookにHTTPリクエストを介してビジターデータを送信するアクションとバッチビジターデータを送信するアクションを追加しました。
2021-11-30
- 302レスポンスをサポートするためのWebhookコネクタの構成オプションを追加しました。
2021-07-20
- コネクタアクションテーブルに各アクションへのリンクを追加しました。
2021-06-07
- HTTPリクエストを介してバッチカスタマイズデータを送信するアクション（Advanced）とバッチ制限セクションを追加しました。
2020-11-05
- Webhook 2-Legged OAuth2および3-Legged OAuth2コネクタのバッチサポートを追加しました。
2018-12-18
- WebhookコネクタのApacheクッキー管理を無効にし、ドメインレベルのクッキーが共有されるのを防ぎました。
2017-08-24
- HTTPリクエストを介してイベントデータを送信する2つの新しいアクションとビジターデータを送信するアクションを追加しました。
- POST-visitorおよびPUT-visitorの2つのアクションを削除しました。アクションはアクションドロップダウンリストには表示されなくなりましたが、アクションが現在あなたのプロファイルにインストールされている場合、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年May月22日