英語からAIを使用して翻訳されました
この記事はAI技術を使用して翻訳されたことにご注意ください。正確性を維持するよう努めていますが、一部の詳細は元のテキストを完全に反映していない場合があります。情報に不明な点がある場合は、英語版を参照してください。
この記事はVoice of Customer Growthプランのお客様に適用されます。
Contentsquare Webhooksを使用すると、ウェブサイトの訪問者が新しい調査回答を提出したときなど、イベントが発生したときに通知を受けることができます。自分のウェブサイトまたはパートナー企業のウェブサイトに「ウェブフック」（URL）を設定し、そのウェブフックをContentsquareと共有すると、イベントが発生したときにイベントペイロードを受け取ります。したがって、Webhooksはリアルタイムでデータをシステムにプッシュする方法です。
技術的には：
ユニークなURLを持つウェブフックを通常は自分のサーバー/ウェブサイトに設定します。
Contentsquareインターフェース内で、調査またはリプレイセグメントにウェブフックURLを入力します。
Contentsquareは、新しい調査回答が作成されるたび、またはリプレイセグメントに一致する新しいリプレイが作成されるたびに、あなたのウェブフックURLにHTTP POSTリクエストを送信します。
なぜWebhooksを使用するのか？
WebhooksはContentsquare APIを補完します。APIはバルクエクスポート（ダウンロード）に最も便利ですが、Webhooksは調査回答やリプレイセグメントに基づくリプレイを即座に受け取るのに便利です。次のような場合にはWebhooksの使用を検討すべきです：
- データを即座に受け取りたい。
- APIをポーリングすることなく、データをシステム（おそらくデータウェアハウス）に送信したい。
- パートナーがWebhooksを介してContentsquareとの統合を提供している。
Webhooksの動作
イベントが発生すると、Contentsquareはすべての設定されたWebhookにメッセージを送信します：
- メッセージはあなたのウェブフックにHTTP POSTリクエストとして送信されます。
- リクエストはUTF-8としてエンコードされます。
- コンテンツタイプは
application/jsonになります。 - リクエストのボディは次のプロパティを持つJSONオブジェクトになります：
-
event- 文字列。このプロパティの値はイベントの名前です。執筆時点ではsurvey_response、replayまたはtest_messageになります。 -
version- 整数。このプロパティは将来の使用のために予約されており、現在は常に1に設定されます。 -
data- このプロパティの値はイベントのデータを持つJSONオブジェクトになります。オブジェクトのフィールドは各イベントに特有です（下記参照）。
-
イベントが発生した後、できるだけ早くイベントを送信します。実際には、数秒以内にメッセージを受け取ることができます。稀にメッセージが遅延することがありますが、各イベントには発生した日時が含まれているため、ウェブフックがメッセージを受信した日時ではなく、その日時を使用することをお勧めします。
Contentsquareは、受信したメッセージの順序がイベントが発生した順序と一致することを保証しません。一部のイベントにはindexパラメータが含まれており、これを使用して順序付けができます。
Webhookの要件
あなたのウェブフックは次の要件を満たす必要があります：
- ウェブフックはHTTPS（TLS）でなければなりません。
- サーバーは10秒以内に応答する必要があります。
- サーバーは任意のHTTP 2XXステータスコード（200から299の間の任意のHTTPステータスコード）で応答する必要があります。
- サーバーはエラーを返さずに予期しないイベントタイプを受け入れる必要があります。
- サーバーは偶発的な重複メッセージを処理する必要があります。Contentsquareはメッセージをウェブフックに一度だけ送信するように最大限努力しますが、それを保証することはできません。したがって、ウェブフックは重複排除のためにメッセージ内の一意の識別子に依存する必要があります。
再試行
Contentsquareはエラーが発生した場合にウェブフックの送信を再試行しようとします。Contentsquareは最大6回まで再試行し、再試行の間に一時停止します：
| 再試行回数 | 再試行前の遅延 |
| 1 | 30秒 |
| 2 | 1分 |
| 3 | 2分 |
| 4 | 5分 |
| 5 | 10分 |
| 6 |
20分 |
Contentsquareは次のいずれかが発生するまで送信を再試行します：
- ウェブフックが2XXステータスコード（すなわち成功した応答）で応答する。
- ウェブフックが410ステータスコードで応答する（この場合、Contentsquareはウェブフックをあなたの調査またはリプレイセグメントから削除します）。
- 最大6回の再試行に達する。
署名とリプレイ防止
Contentsquareのウェブフックは、受信したペイロードが本当にContentsquareからのものであることを確認するために、2つのセキュリティ技術を使用しています：
- あなたのウェブフックに送信されるすべてのペイロードはHMACで署名されています。データが本当にContentsquareから来たことを確認するために、署名を検証することを強くお勧めします。
- すべてのペイロードにはタイムスタンプが含まれているため、データが最近数分以内にContentsquareから送信されたことを確認できます。これにより、リプレイ攻撃を軽減することができます。なぜなら、Contentsquareがこのデータを最近数分以内にあなたに送信したことを確信できるからです。
ペイロード署名の確認
署名は、com-Contentsquare-signatureというカスタムヘッダーとしてあなたのウェブフックに送信されます。署名が有効であることを確認するには、次の手順を実行する必要があります：
1. 受信したペイロードから署名を生成する
2. 生成した署名がヘッダー内の署名と一致するか確認する
HMAC-SHA3-256、ペイロード（バイトとして）および署名キーを使用して署名を生成できます。Contentsquareサイトの署名キーを取得するには、Contentsquareアプリケーション内のウェブフック統合設定を開き、「ウェブフックキーを表示」をクリックします。
署名を生成したら、com-Contentsquare-signatureヘッダーに送信された署名と比較できます。2つの値が一致すれば、署名は正常に検証されたことになります。一致しない場合は、ペイロードを破棄し、それに基づいて行動しないでください。
リプレイ攻撃からの保護
HMAC署名により、Contentsquareがウェブフックペイロードを作成したことを確認できますが、攻撃者が同じペイロードを再度（何度も！）送信する可能性があります。その場合、署名の検証は成功します。これらの「リプレイ攻撃」から保護するために、ペイロード内にタイムスタンプも送信します。タイムスタンプに指定された日付と時刻が古すぎる場合（過去5分以上を推奨）、ペイロードを破棄する必要があります。
タイムスタンプを確認するには、まず上記に記載されているようにHMAC署名を確認する必要があります。攻撃者がペイロード内に有効なタイムスタンプを送信する可能性があるため、タイムスタンプを確認する前にHMAC署名を確認してください。タイムスタンプはUNIXタイムスタンプであり、Unixエポックからの秒数を意味します。以下の例ペイロードで例のタイムスタンプを見ることができます。
ペイロード
Contentsquareは将来的にこれらのペイロードに追加のフィールドを追加する可能性があるため、ウェブフックは予期しないフィールドが存在してもエラーを発生させないようにしてください。記載された型に加えて、任意のフィールドはnullに設定することができることに注意してください。
調査回答
イベント名: survey_response
-
id整数 - アンケート回答の一意の識別子。 -
index整数 - このアンケート回答のアンケート内でのインデックス。 -
api_id文字列 - このアンケート回答を参照する公開ID（UUIDを含む）。 -
response_url文字列 - Hotjarアプリ内で回答を表示するためのリンク。 -
site_id整数 - Hotjarサイトの一意の識別子。 -
survey_id整数 - アンケートの一意の識別子。 -
survey_name文字列 - アンケートの名前。 -
survey_url文字列 - Hotjarアプリ内でアンケートを表示するためのリンク。 -
device文字列 - アンケート回答を提出するために使用されたデバイスタイプ。 "tablet"、"mobile"、または "desktop" になります。 -
browser文字列 - アンケート回答を提出するために使用されたブラウザの名前。 -
os文字列 - アンケート回答を提出するために使用されたオペレーティングシステムの名前。 -
country_code文字列 - アンケート回答が作成された国のコード。これらのコードのリストについては、ISO 3166国コードを参照してください。 -
country_name文字列 - アンケート回答が作成された国。 - hotjar_user_id 文字列 - アンケート回答を提出したユーザーのHotjarユーザーID（UUID）。
-
created_str文字列 - アンケート回答が作成された日時をISO 8601文字列として表したもの。 -
created_timestamp整数 - アンケート回答が作成された日時をUNIXタイムスタンプとして表したもの。 -
is_completeブール値 - アンケート回答が完了しているかどうかを示すフラグ。 -
recording_url文字列 - そのアンケート回答を含むHotjar録画へのリンク（存在する場合）。 -
response_origin_url文字列 - ユーザーがアンケート回答を提出したサイトのURL。 -
window_width整数 - アンケート回答を提出する際のユーザーのウィンドウの幅。 -
window_height整数 - アンケート回答を提出する際のユーザーのウィンドウの高さ。 -
user_attributesオブジェクト - Hotjar Identify API によって提供されたユーザーの属性。オブジェクト内の各キーと値は次のことを表します：-
key文字列 - ユーザー属性の名前。 -
value文字列/整数/浮動小数点/ブール値/日時 - ユーザー属性の値。 -
questions配列/リスト - 調査の質問と回答。各要素には次のフィールドがあります：-
question_id整数 - 質問のユニークID。 -
question_text文字列 - 質問のテキスト。 -
question_type文字列 - 質問のタイプ。これはreaction、long-text、short-text、single-option、multiple-option、email、1-5-rating、1-7-rating、npsまたはunknown。 -
answers配列/リスト - 質問への回答。各回答には次のフィールドがあります：-
answer文字列 - ユーザーが与えた回答。 -
comment文字列 - ユーザーが残したコメント（あれば）。
-
-
-
ユーザーが回答しなかった質問はペイロードに含まれないことに注意してください。
sample 文字列 - 常に文字列「data」に設定されます。
例のペイロード
調査回答
{
"event": "survey_response",
"data": {
"id": 42,
"index": 1,
"api_id": "response_f8ccb724-8110-48d0-8715-2138be7a9c06",
"response_url": "https://insights.hotjar.com/link/goes/here",
"site_id": 42,
"survey_id": 42,
"survey_name": "テスト調査",
"survey_url": "https://insights.hotjar.com/link/goes/here",
"device": "デスクトップ",
"browser": "Chrome",
"os": "Windows",
"country_code": "MT",
"country_name": "マルタ",
"hotjar_user_id": "90fc1180-90b4-463c-9d1f-3415477f0168",
"created_str": "2023-06-07T11:13:05.193076Z",
"created_timestamp": 1686136385,
"is_complete": false,
"recording_url": "https://insights.hotjar.com/r?site=14&recording=12345",
"response_origin_url": "https://www.example.com",
"window_width": 1280,
"window_height": 1024,
"user_attributes": {
"test_ua_one": "value",
"test_ua_two": true
},
"questions": [
{
"question_id": 1,
"questiom_text": "質問 1",
"question_type": "short-text",
"answers": [
{
"answer": "質問 1 の回答がここに入ります",
"comment": null
}
]
},
{
"question_id": 2,
"questiom_text": "質問 2",
"question_type": "long-text",
"answers": [
{
"answer": "質問 2 の回答がここに入ります\n\n 新しい行",
"comment": null
}
]
},
{
"question_id": 3,
"questiom_text": "質問 3",
"question_type": "email",
"answers": [
{
"answer": "support@hotjar.com",
"comment": null
}
]
},
{
"question_id": 4,
"questiom_text": "質問 4",
"question_type": "single-option",
"answers": [
{
"answer": "ラジオボタン？",
"comment": "コメント"
}
]
},
{
"question_id": 5,
"questiom_text": "質問 5",
"question_type": "multiple-option",
"answers": [
{
"answer": "これ",
"comment": "コメント"
},
{
"answer": "あれ",
"comment": "コメント"
}
]
},
{
"question_id": 6,
"questiom_text": "質問 6",
"question_type": "1-5-rating",
"answers": [
{
"answer": "3",
"comment": null
}
]
},
{
"question_id": 7,
"questiom_text": "質問 7",
"question_type": "1-7-rating",
"answers": [
{
"answer": "3",
"comment": null
}
]
},
{
"question_id": 8,
"questiom_text": "質問 8",
"question_type": "nps",
"answers": [
{
"answer": "3",
"comment": null
}
]
},
{
"question_id": 9,
"questiom_text": "質問 9",
"question_type": "reaction",
"answers": [
{
"answer": "3",
"comment": null
}
]
},
{
"question_id": 10,
"questiom_text": "質問 10",
"question_type": "short-text",
"answers": [
{
"answer": "",
"comment": null
}
]
}
]
},
"version": 1,
"timestamp": 473385600
}