AIを使用して英語から翻訳されました
この記事はAI技術を使用して翻訳されたことにご注意ください。正確性を維持するよう努めていますが、一部の詳細は元のテキストを完全に反映していない場合があります。情報に不明な点がある場合は、英語版を参照してください。
概要
Webhooksを使用すると、ウェブサイトの訪問者が新しい調査回答を提出したときなど、イベントが発生した際に通知を受けることができます。自分のウェブサイトまたはパートナー企業のウェブサイトに「webhook」（URL）を設定し、そのwebhookをContentsquareと共有すると、イベントが発生したときにイベントペイロードを受け取ります。したがって、Webhooksはリアルタイムでデータをシステムにプッシュする方法です。
技術的には：
- ユニークなURLを持つwebhookを通常は自分のサーバー/ウェブサイトに設定します。
- 調査を設定する際にForward ResponseセクションにwebhookのURLを入力します。
- 新しい調査回答が作成されるたびに、私たちはあなたのwebhook URLにHTTP POSTリクエストを送信します。
なぜWebhooksを使用するのか？
WebhooksはSurveys APIを補完します。Surveys APIはバルクエクスポート（ダウンロード）に最も便利ですが、webhooksは調査回答を即座に受け取るのに便利です。次のような場合にはwebhooksの使用を検討すべきです：
- データを即座に受け取りたい。
- 私たちのAPIをポーリングすることなく、データをシステム（おそらくデータウェアハウス）に送信したい。
- パートナーがwebhooksを介してHotjarとの統合を提供している。
Webhooksの動作
イベントが発生すると、設定されたすべてのwebhookにメッセージを送信します：
- メッセージはあなたのwebhookにHTTP POSTリクエストとして送信されます。
- リクエストはUTF-8としてエンコードされます。
- コンテンツタイプは
application/jsonになります。 - リクエストのボディは次のプロパティを持つJSONオブジェクトになります：
-
event- 文字列。このプロパティの値はイベントの名前です。執筆時点ではsurvey_responseまたはtest_messageになります。 -
version- 整数。このプロパティは将来の使用のために予約されており、現在は常に1に設定されます。 -
data- このプロパティの値はイベントのデータを持つJSONオブジェクトになります。オブジェクトのフィールドは各イベントに特有です（下記参照）。
-
イベントが発生した後、できるだけ早くイベントを送信します。実際には数秒以内にメッセージを受け取るはずです。稀にメッセージが遅延することがありますが、各イベントには発生した日時が含まれているため、webhookがメッセージを受信した日時ではなく、その日時を使用することをお勧めします。
Contentsquareは、受信したメッセージの順序がイベントが発生した順序と一致することを保証しません。一部のイベントには順序付けに使用できるindexパラメータが含まれています。
Webhookの要件
あなたのWebhookは以下の要件を満たす必要があります：
- WebhookはHTTPS（TLS）でなければなりません。
- サーバーは10秒以内に応答する必要があります。
- サーバーは任意のHTTP 2XXステータスコード（200から299の間の任意のHTTPステータスコード）で応答する必要があります。
- サーバーはエラーを返さずに予期しないイベントタイプを受け入れる必要があります。
- サーバーは偶発的な重複メッセージを処理する必要があります。私たちはWebhookにメッセージを一度だけ送信するように最善を尽くしますが、それを保証することはできません。したがって、あなたのWebhookは重複排除のためにメッセージ内の一意の識別子に依存する必要があります。
再試行
エラーが発生した場合、Webhookの送信を最大6回再試行します。再試行の間に一時停止します：
| 再試行回数 | 再試行前の遅延 |
| 1 | 30秒 |
| 2 | 1分 |
| 3 | 2分 |
| 4 | 5分 |
| 5 | 10分 |
| 6 | 20分 |
以下のいずれかが発生するまで、送信を再試行します：
- Webhookが2XXステータスコード（すなわち、成功した応答）で応答します。
- Webhookが410ステータスコードで応答します（この場合、私たちはあなたの調査からWebhookを削除します）。
- 最大6回の再試行に達します。
署名と再送信防止
私たちのWebhookは、受信するペイロードが本当に私たちからのものであることを確認するために、2つのセキュリティ技術を使用しています：
- あなたのWebhookに送信されるすべてのペイロードはHMACで署名されています。データが本当に私たちから送信されたことを確認するために、署名を検証することを強くお勧めします。
- すべてのペイロードにはタイムスタンプが含まれているため、データが最近数分以内に/ usから送信されたことを確認できます。これにより、再送信攻撃を軽減できます。なぜなら、私たちがこのデータを最近数分以内にあなたに送信したことを確信できるからです。
ペイロード署名の確認
署名はcom-hotjar-signatureというカスタムヘッダーとしてあなたのWebhookに送信されます。署名が有効であることを確認するには、以下の手順を実行する必要があります：
- 受信したペイロードから署名を生成します。
- 生成した署名がヘッダー内の署名と一致するか確認します。
HMAC-SHA3-256、ペイロード（バイトとして）および署名キーを使用して署名を生成できます。サイトの署名キーを取得するには、統合ページを開き、'Webhook'をクリックします。次に'Webhookキーを表示'をクリックします。
署名を生成したら、com-hotjar-signature ヘッダーに送信された署名と比較できます。2つの値が一致すれば、署名は正常に検証されたことになります。一致しない場合は、ペイロードを破棄し、それに基づいて行動しないでください。
リプレイ攻撃からの保護
HMAC署名により、私たちがウェブフックペイロードを作成したことを確認できますが、攻撃者が同じペイロードを再度（何度も！）送信することができ、署名の検証は成功します。これらの「リプレイ攻撃」から保護するために、ペイロード内にタイムスタンプも送信します。タイムスタンプに指定された日付と時刻が古すぎる場合（過去5分以上を推奨）、ペイロードを破棄してください。
タイムスタンプを検証するには、まず上記のようにHMAC署名を検証し、その後タイムスタンプを確認する必要があります。攻撃者はペイロード内に有効なタイムスタンプを送信することができるためです。タイムスタンプはUNIXタイムスタンプであり、Unixエポックからの秒数を示します。以下の例ペイロードで例のタイムスタンプを見ることができます。
ペイロード
将来的にこれらのペイロードに追加のフィールドを追加する可能性があるため、ウェブフックは予期しないフィールドが存在してもエラーを発生させないようにしてください。記載された型に加えて、任意のフィールドは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文字列 - その調査回答を含む録音へのリンク（存在する場合）。 -
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文字列 - ユーザーが残したコメント（あれば）。
-
-
ユーザーが回答しなかった質問はペイロードに含まれていないことに注意してください。
例のペイロード
調査回答
{
"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
}
テストメッセージ
{
"event": "test_message",
"version": 1,
"timestamp": 473385600,
"data": {
"sample": "data"
}
}