SurveyCake Webhook

繁中 | English

• 簡介
• 流程
• 測試工具
• Q & A

簡介

透過 SurveyCake Webhook，你可以自行開發 API 去依據問卷蒐集到的答案進行個別的行為觸發。本文件將介紹 SurveyCake Webhook 串接流程及答案解密方法。

流程

• Step 1. 設定網址
• Step 2. 訪問 API
• Step 3. 查詢答案
• Step 4. 解密答案
• Step 5. 運用資料

---

Step 1. 設定網址

SurveyCake 提供兩種網址設定，讓你可以針對填答的內容做額外的行為觸發；一為 系統通知 > Webhook，另一為 自訂感謝頁：

• 系統通知 > Webhook
  • 使用者填答後，SurveyCake 將使用 POST request，訪問你所設定的 Webhook URL。
  • 適用於後端 API
• 自訂感謝頁
  • 使用者填答後，SurveyCake 將使用 GET request 將所需參數帶入，並且跳轉至自訂感謝頁。
  • 適用於前端 Script

以下步驟將以 Webhook URL 做介紹，若想使用自訂感謝頁，可以直接前往 測試工具 段落。

首先，請在後台設定一個 Webhook URL 來接收我們的通知。

---

Step 2. 訪問 API

• 每當問卷有新的填答後，我們會使用 POST requrest 夾帶 svid & hash 參數送至你所設定的 Webhook URL 網址。
• 你必須使用取得的 svid & hash 組合成 Webhook Query API，格式如下：
  • https://{SURVEYCAKE_DOMAIN}/webhook/{VERSION}/{SVID}/{HASH}
• 版本號 (VERSION) 目前請使用 v0

👉 Webhook Query API 範例 👈

• POST svid: yPZQe
• POST hash: 5fd521e89436c471155f39de9c05bf4c

https://{SURVEYCAKE_DOMAIN}/webhook/v0/yPZQe/5fd521e89436c471155f39de9c05bf4c

---

Step 3. 查詢答案

訪問組合好的 Webhook Query API 可以取得該次 加密填答結果。

👉 加密填答結果 範例 👈

C8jl3+0MLRWZAQtvzcbMJfMdE9F/CkH3qeQd93CdWntbFMk+mWOvSSsE65g5U4Sj/26btUWunpV1Gk9uM1Ltyk+RpqFC+Ve2d8uExGFortYHUuZ32NMeJd1h1DqDJpJy/1epiYMXSDFOEyJUIE1X8zamJAi6D0R5IwADXLVw315PW6B7t+IejkKJNrjlL6cgtI8B1PCAh58oMUQydrJd73zRY4f9O4yC5ZNdg4nloVR4qYWyFkFZOOCE6yExtnMzV/gg4e9gnlYAPb31Wlb3Scjl2akaiO8G78OBWa0r5cmN3MmLQ0NcahViUqOdJ+8v+jPwzh1wIflIuho+JyrgoQ==

---

Step 4. 解密答案

剛剛取得的 加密填答結果，必須透過Hash key & IV key 進行解密，才可以拿到可閱讀的填答結果 JSON。Hash key 及 IV Key 可以在 SurveyCake 後台找到，截圖如下。

我們使用 AES-128-CBC (zero-padding) 方式加密，所以請務必使用 AES-128-CBC (zero-padding) 進行解密，其他的解密方式，無法解出正確的資訊，以下是幾種語言的解密示範：

• Javascript
  • 範例使用 crypto-js
  • 我們也提供 Javascript ES5 範例
• PHP
  • 範例使用 openssl_decrypt
• NodeJs
  • 範例使用 crypto
• Python
  • 範例使用 PyCryptoDome library
• Swift
  • 範例使用 CommonCrypto library
• Java
  • 範例使用 javax.crypto

👉 解密後答案 範例 👈

{
	"svid": "yPZQe",
	"title": "Webhook Answer Demo",
	"submitTime": "2018-06-28 04:05:47",
	"result": [
		{
			"subject": "What's your name?",
			"type": "TXTSHORT",
			"sn": 0,
			"answer": ["SurveyCake Marketing"],
			"otherAnswer": []
		},
		{
			"subject": "Gender",
			"type": "CHOICEONE",
			"sn": 1,
			"answer": ["Both"],
			"otherAnswer": ["會出現填寫其他選項中的文字"]
		}
	]
}

Step 5. 運用資料

解密完成後，你可以撰寫 Webhook 邏輯，觸發額外的行為，例如：

• 寫入額外的資料庫
• 寄送 Email
• Webhook 到第三方服務（ex: slack)
• Google Spreadsheet

你可以在 examples 資料夾找到一些範例。

測試工具

SurveyCake 提供一個 Webhook Answer Preview 的測試工具，利用 自訂感謝頁 的設定，讓你快速預覽答案的格式。

• Github Repo: https://github.com/SurveyCake/webhook-answer-preview
• Demo: https://surveycake.github.io/webhook-answer-preview/

Q & A

1. 填答結果會是什麼格式？

每份填答結果解密之後會是 JSON 格式，內容包含 Survey Id, Survey Title, 填答時間 以及 填答內容。

{
	"svid": "SURVEY ID",
	"title": "SURVEY TITLE",
	"submitTime": "2018-06-28 04:05:47",
	"result": [
		// ....
	]
}

result 是以陣列型態包含著所有的問題及答案，我們提供 Subject Title, Subject Type, Subject Number, Answer，格式範例如下：

"result": [
	{
		"subject": "What's your name?",
		"type": "TXTSHORT",
		"sn": 0,
		"answer": ["SurveyCake Marketing"],
		"otherAnswer": []
	},
	{
		"subject": "Gender",
		"type": "CHOICEONE",
		"sn": 1,
		"answer": ["Both"],
		"otherAnswer": ["會出現填寫其他選項中的文字"]
	}
]

以下為 Subject Type 對照表：

Type	題型名稱
TXTSHORT	單行文字
TXTLONG	多行文字
CHOICEONE	單選題
CHOICEMULTI	多選題
NEST	矩陣題
NESTCHILD	矩陣子題
DIGITINPUT	數字題
DIGITSLIDE	數字滑桿
ITEMSORT	項目排序
RATINGBAR	星級評分
PICKFROM	重複核選題
QUOTE	引言
STATEMENT	分類標題
DATEPICKER	日期
DIVIDER	分隔線/分頁

2. 問卷如果編輯後，Webhook URL 是否也要跟著修改呢？

我們建議你在撰寫 Webhook URL 時，不要使用 answer 陣列順序撰寫 Webhook 邏輯，應該使用 sn 作為比對的依據較佳。

因為問卷修改了題目標題、題目順序後，answer 陣列的順序會變動，此時你可能就會需要調整 Webhook 邏輯，而 sn 為每個題目的在問卷內的不重複編號，所以無論題目怎麼編輯順序，同一個題目 sn 不會變動。

3. 刪除的題目還會出現在填答結果內嗎？

不會，刪除的題目，就不會出現在填答結果內了，所以撰寫邏輯時，建議先判斷資料是否存在後再使用。