如果你希望將 OOOPEN Lab 製作的心理測驗或互動專案的填答內容、結果，自動傳回自家網站、CRM、Google Sheet 等內部系統，現在可以透過 API Key 串接 Webhook 功能輕鬆完成！
無論你是希望自動分類潛在客群，或是簡化資料整理流程，這篇文章將一步步教你如何啟用 Webhook，並說明支援回傳的資料類型、觸發時機與實際應用方式，協助你把互動專案的影響力延伸到更多場景。
目錄
要怎麼啟用 Webhook？有回傳的資料範例嗎？
- 成為付費用戶，才能在方案啟用時設定（我該怎麼挑選方案？）
- 從後台的「帳號設定」頁面，進入「開發人員專區」
- 初次進入「開發人員專區」時，請先生成新的 API Key
- 生成 API Key 之後，即可開始設定 Webhook 事件
- Webhook 會在兩個時間點傳送，可視需求設定。
- 開始填答時：玩家進入題目頁時
- 填答完成時：玩家完成填答，進入結果頁時（完成填答的定義）
- 成功設定後，若符合觸發條件，即會發送 POST 通知到指定網址
以下為傳遞的 JSON 資料範例
{
"data": {
"answerId": "o1VepeqjgSbe6XxeJlZs",
"quizId": "nvCwKZUvGw43KTrMth3V",
"startedAt": "2024-04-11T08:44:10.782Z",
"ref": {
"id": "gI11io",
"label": "渠道名稱"
},
"utm": {
"campaign": "",
"id": "",
"source": ""
},
"fromQuiz": {
"answerId": "",
"quizId": ""
},
"finishedAt": "2024-04-11T08:44:10.943Z",
"result": {
"id": "default",
"label": "結果名稱"
},
"duration": 2513,
"answers": [
{
"id": "VvsB5w",
"duration": 1297,
"value": "adaff",
"title": "第一題"
},
{
"id": "WSgpX9",
"duration": 1217,
"value": "其他",
"other": "用戶填入的其他回答",
"title": "第 3 題"
}
]
},
"type": "finish",
"timestamp": "2024-04-11T08:50:57.315Z"
}資料欄位有哪些？
以下為「專案填答相關」的資料欄位說明
| data | 填答資料（下方詳述） |
| type | 事件別（”start”或”finish”） |
| timestamp | 時間戳記（ISO 國際標準時間） |
以下為「所有事件別共用」的填答資料說明
| answerId | 填答序號 |
| quizId | 測驗序號 |
| startedAt | 開始填答時間（ISO 國際標準時間） |
| ref | 渠道來源（下方詳述） |
| utm | UTM 紀錄（下方詳述） |
| fromQuiz | 其它模組來源（下方詳述） |
以下為「限定已完成事件別」的填答資料說明
| finishedAt | 完成填答時間（ISO 國際標準時間） |
| result | 結果 |
| duration | 總填答時間（ms 毫秒） |
| answers | 填答內容，陣列 |
以下為「填答內容」的填答資料說明
| id | 題目ID |
| duration | 填答時間 (ms毫秒) |
| value | 填答內容 |
| other | 其他選項內容 |
| title | 題目標題 |
以下為「ref（渠道來源）」的填答資料說明
| id | 渠道的網址 ID |
| label | 後台設定的渠道名稱 |
以下為「UTM（渠道來源）」的填答資料說明，需要購買「匯出 UTM 紀錄」進階功能才能搜集得到
| campaign | utm_campaign 資料 |
| id | utm_id 資料 |
| source | utm_source 資料 |
以下為「fromQuiz（其它模組來源）」的填答資料說明，需要購買「結果頁串連其它模組」進階功能才能搜集得到
| answerId | 來源填答 ID |
| quizId | 來源測驗 ID |
有哪些資料無法回傳？
因為觸發條件僅有「開始填答」與「完成填答」，故填答完成後的資料：包括「留資料/填答表單」的填寫資料、計分測驗排行榜等資料，都無法回傳喔！
我們建議選用的安全性機制
Webhook 傳遞會附加上`x-ooopenlab-signature` Header，可以用該 Header 來驗證是否是 OOOPEN Lab 平台傳送的通知。
驗證方式為以下兩個步驟：
- 將「填答資料」(即 data 這個 JSON 物件) 轉成 JSON 字串後，搭配 API Key，用 HMAC-SHA256 演算法，得到 hex 字串
- 若與`x-ooopenlab-signature`相等，那就可以確定是 OOOPEN Lab 平台傳送的通知
範例：
若傳遞資料為 `{"test":123}` ，API Key為 `abcdef0123`，則可得到 hex 字串為 `c6dddde7ffbf0c651277f40b52cc8a07d80493982eaa6a10b7ab30bd6d9d4fe7`範例程式碼（Node.js）：
const crypto = require('crypto');
const key = 'abcdef0123';
const data = '{"test":123}' ;
const signature = crypto
.createHmac("sha256", key)
.update(data)
.digest("hex");
// signature === 'c6dddde7ffbf0c651277f40b52cc8a07d80493982eaa6a10b7ab30bd6d9d4fe7'
