如何用 Webhook 串接 OOOPEN Lab 測驗資料？

如果你要把測驗或集點活動的資料傳到自己的系統，請在帳號的「開發人員專區」建立活動資料回傳。這組設定會把指定專案的事件送到你的接收網址。

先確認：活動資料回傳目前僅開放給 Beta 測試名單中的帳號。已開通的帳號可依本篇建立新連線；尚未開通的帳號請先與我們聯繫。帳號層級的舊版 Webhook 不能新增或編輯，本文後半段保留舊設定的資料格式與安全性說明。

要更新 SHOPLINE 會員標籤或發放回饋？先選擇設定方式

若需求是依測驗結果為 SHOPLINE 會員加上標籤，或發放購物金、會員點數、領取型優惠券，已開通 SHOPLINE 自動化 Beta 的專案擁有者，可先確認內建的「SHOPLINE 行銷活動自動化」是否適用；這些內建動作不必另外架設 Webhook 接收系統。請依SHOPLINE 會員登入與行銷活動自動化教學操作，先確認專案適用條件與商店授權。

需要把填答或活動資料送到自己的 CRM、會員系統，或由自己的系統處理後續業務時，繼續依本篇設定活動資料回傳。品牌會員登入、SHOPLINE 自動化與活動資料回傳是各自獨立的設定與開通條件。

如果自己的 Webhook 接收系統已會發放同一份回饋，啟用內建自動化前，先確認由哪一邊負責發放，避免兩邊各發一次。

建立活動資料回傳

開啟「帳號設定」的「開發人員專區」。
建立一組活動資料回傳。
填入接收資料的網址。
選擇接收格式。新連線請使用新格式。
選擇要回傳的事件。
選擇允許回傳的專案或集點卡。
儲存設定，並用實際活動觸發事件測試。

活動資料回傳的設定名稱只用來辨識這組連線。每組連線都有自己的簽章金鑰。接收端不使用帳號 API Key。

選擇要回傳的事件

請依活動目的選擇事件。事件只會在符合觸發條件時送出。

事件	什麼時候送出	常見用途
回答完成	完成填答並儲存填答紀錄後	把測驗結果交給品牌系統
任務完成	玩家完成集點卡上的任務	記錄任務完成狀態
實際加點	平台實際將點數加到集點卡	同步點數異動
平台兌換	玩家在平台完成兌換	同步平台上的兌換紀錄

勾選測驗專案，才能收到該測驗的「回答完成」事件。

單獨的集點卡或活動頁：任務完成、實際加點與平台兌換事件來自集點卡或活動頁本身。
活動專案群組：任務完成與實際加點事件來自群組內的遊戲專案，平台兌換事件來自集點卡。

允許專案要勾選產生事件的專案。若回傳設定選擇會員資料空間，來源專案必須綁定該空間；只接收「回答完成」時，也可選「不綁會員身分」。

接收資料時要注意什麼

接收端需要依事件識別碼去重。同一事件可能因重試而收到多次。
接收端回應 HTTP 200，只代表接收端收下資料，不代表品牌系統已完成貼標、發券或更新會員資料。
如果你要看的資訊沒有出現，或資料沒有送到接收端，請先檢查事件、允許專案、接收網址與接收端 Log。
平台提供的是文件中定義的資料格式。接收端仍可能需要依自己的 CRM 或資料工具進行欄位對應。

用 webhook.site 做測試

你可以先用 webhook.site 產生測試網址，再把網址填入活動資料回傳設定。完成測驗或其他測試事件後，到 webhook.site 查看收到的資料。

示範圖片：畫面中的網址與資料為示範說明，請自行設定測試環境。

確認平台送達狀態

回到活動資料回傳設定，查看傳送紀錄。狀態顯示「已送達」代表 OOOPEN Lab 已將資料送到接收網址。

示範圖片：畫面中的連線與事件資料僅供說明，實際內容會依你的測試結果顯示。

新格式的主要欄位

以下欄位適用於「新格式」。選擇「既有 Webhook 格式」時，事件會包在 data 內，外層另有 type 與 timestamp。完整結構與兩種格式的驗章方式，請參考如何設定品牌活動資料回傳？。

欄位	用途
`type`	事件類型，例如 `finish`、任務完成、實際加點或平台兌換事件。
`occurredAt`	事件發生時間。
`externalUserId`	事件使用的玩家識別值，不是原始 LINE userId。未登入時可為每筆答案各自產生的 `anon:v1:`，不能用來跨填答辨識同一人。
`brandMemberId`	有對應品牌會員資料時可能帶回的原始會員識別碼，不是每筆事件都一定存在。
`payload.quizId`、`payload.answerId`	回答完成事件的測驗專案與填答紀錄識別碼。
`payload.result`、`payload.answers`	回答完成事件中的結果代碼與作答資料，有值才會出現。作答內容過大時會省略 `answers`，改帶 `payload.answersTruncated: true`。
點數與兌換欄位	任務完成、實際加點與平台兌換事件中的活動、集點卡、點數及紀錄資訊。

收到資料不等於品牌端已完成後續動作。Webhook 只負責把事件送到你的接收網址；是否貼標、發券或寫入會員資料，要看你的接收系統如何處理。

舊版 Webhook：既有設定參考

版本提醒：以下內容只適用於仍在使用帳號層級舊版 Webhook 的既有設定。舊版 Webhook 目前不能新增或編輯；若要建立新的資料回傳，請使用本篇前半段的「活動資料回傳」。新版不提供「開始填答」事件，也不使用帳號 API Key 建立新的回傳連線。

成為付費用戶，才能在方案啟用時設定（我該怎麼挑選方案？）
過去可從後台的「帳號設定」頁面進入「開發人員專區」。
過去初次進入「開發人員專區」時，需先生成 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

舊版欄位說明：以下 oauthUser、provider 與相關欄位只適用於舊版 Webhook payload，不代表新版活動資料回傳一定會提供相同欄位。若使用新版，請改看前文的「新格式的主要欄位」。

💡 若測驗啟用可供 Webhook 識別的 OAuth／會員登入方式，payload 可能帶有 oauthUser。能查到會員資料時，id 是識別會員的主要欄位；專案具備「記錄玩家社群登入的 Email」或「結果頁蒐集玩家資料」其中一項加購時，系統會附上可取得的 email；provider 的條件較窄，只有具備 OAuth 進階功能權限（前者）時才會附上。兩項加購都沒有時，email 與 provider 這兩個欄位不保證存在；找不到會員紀錄時，oauthUser 也可能是 null。想看如何串接自家 LINE Login，請參考：如何用自訂 OAuth 串接 LINE Login，讓 OOOPEN Lab 測驗對得起官方帳號好友 ID？

舊版有哪些資料無法回傳？

因為觸發條件僅有「開始填答」與「完成填答」，故填答完成後的資料：包括「留資料/填答表單」的填寫資料、計分測驗排行榜等資料，都無法回傳唷！

舊版安全性驗證方式

僅適用舊版：舊版 Webhook 傳遞會附加上 x-ooopenlab-signature Header，並使用帳號 API Key 驗證是否由 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'

驗證舊版 Webhook 回傳來源

本節只適用於帳號層級舊版 Webhook，使用 x-ooopenlab-signature Header 與帳號 API Key。活動資料回傳的「新格式」使用 X-OOOPEN-Webhook-Timestamp、X-OOOPEN-Webhook-Event-Id 與 X-OOOPEN-Webhook-Signature 等 Header；「既有 Webhook 格式」雖沿用 x-ooopenlab-signature，卻使用該組連線的獨立簽章金鑰。請依活動資料回傳教學驗章，勿混用金鑰與計算方式。

使用收到的 data 原始 JSON bytes 與帳號 API Key，計算 HMAC-SHA256，輸出小寫 hex。
將產生的簽章與 x-ooopenlab-signature 比對。
驗證失敗時，不要把資料當成已確認的事件。

排查順序：先確認事件與允許專案，再確認接收網址與接收端 Log。若接收端沒有收到資料，請提供事件類型、觸發時間與接收端紀錄，方便釐清問題。