Webhook 可讓 WEBA 在指定事件發生後，將資料自動傳送到你的外部系統。如果你想把 WEBA 的互動資料同步到 CRM、資料庫、自動化工具或自家後台，Webhook 會比手動匯出更即時。
基本規格
WEBA 以 HTTPS POST 傳送 Webhook 請求
請求內容格式為 application/json
每筆請求都會帶上 X-Weba-Signature-256，建議在伺服器端驗證，確認請求確實來自 WEBA
建立成功後，系統會提供一次性的 Webhook Secret；關閉視窗後無法再次查看，請立即複製保存
開始前請先準備
一組可由外部網路存取的接收端 URL
確認接收端能處理 POST 請求與 JSON payload
請使用桌機版後台新增或編輯 Webhook；手機版僅支援查看列表
使用限制
範圍 | 上限 |
|---|---|
每個帳號 | 10 個 Webhook |
每個專案 | 2 個 Webhook |
以上限制不分方案，所有方案一致。
如何新增 Webhook
1. 進入 Webhook 管理
登入 WEBA 後，前往欲設定的專案，從左側選單點選 Webhook 管理。
2. 點選 + 新增 Webhook
系統會跳出 新增 Webhook 視窗。
3. 填寫欄位
欄位 | 說明 |
|---|---|
名稱 | 自訂這筆 Webhook 的名稱 |
層級 | 選擇 專案 或 元件 |
選擇元件類型 | 僅在層級選 元件 時顯示 |
驗證 URL | 填入接收端 URL |
選擇事件（多選） | 依層級選擇要監聽的事件 |
4. 按下 確定
送出成功後：
Webhook 立即出現在 Webhook 管理 列表，預設狀態為 啟用
系統跳出 Webhook Secret 視窗
5. 保存 Webhook Secret
這組 Secret 只會完整顯示一次。 請立即複製並存放在安全位置，後續伺服器端驗證簽章時需要用到。若遺失，必須刪除後重新建立 Webhook。
如何管理既有 Webhook
在 Webhook 管理 列表中，每筆 Webhook 可以：
啟用 / 停用：暫停推送而不刪除設定
編輯：修改名稱、URL、監聽事件（欄位與新增時相同）
刪除：永久移除
查看傳送紀錄：排查推送是否正常
如何查看傳送紀錄
在操作欄點選 查看紀錄，可進入 傳送紀錄 頁。
列表欄位：
欄位 | 說明 |
|---|---|
傳送時間 | 事件觸發的時間戳 |
HTTP 回應碼 | 接收端回傳的狀態碼 |
層級 | 專案或元件 |
事件 | 觸發的事件名稱 |
處理時間 | 從送出到收到回應的耗時 |
點進單筆紀錄，可在 傳送紀錄詳情 看到：
URL：實際推送的目標網址
Payload 大小
嘗試次數：格式為 1 / 8（目前嘗試次 / 最大上限）
請求：含 Headers 與 Payload 完整內容
回應：接收端實際回傳的內容
支援事件
專案層級
API event | 後台顯示名稱 |
|---|---|
site.save | 儲存專案 |
site.publish_update | 發佈專案變更 |
site.close | 關閉專案 |
site.publish | 網站發佈 |
元件層級
API event | 後台顯示名稱 |
|---|---|
lottery.add_award | 新增抽獎獎品 |
lottery.winner | 抽獎中獎 |
lottery.form_submit | 新抽獎表單填寫 |
lottery.empty_award | 抽獎獎品已空 |
poll.new_submit | 新投票填寫 |
newsletter.new_subscribe | 新電子報訂閱 |
personality_test.new_submit | 新心理測驗填寫 |
form.new_submit | 新表單填寫 |
Webhook 請求格式
共通 Headers
每筆請求都會帶上以下 headers：
Header | 說明 |
|---|---|
Content-Type | application/json |
User-Agent | WEBA-Webhook/1.0 |
X-Weba-Event | 觸發的事件名稱 |
X-Weba-Timestamp | 事件發生時間（ISO 8601，例如 2026-04-30T05:58:50.015Z） |
X-Weba-Signature-256 | HMAC-SHA256 簽章，用於驗證來源 |
X-Weba-Delivery | 本次推送的唯一識別碼 |
共通 Payload 欄位
大多數事件的 Payload 頂層欄位如下：
欄位 | 說明 |
|---|---|
event | 事件名稱，例如 form.new_submit |
event_id | 本次事件的唯一識別碼，與 X-Weba-Delivery header 相同 |
webhook_id | 觸發此推送的 Webhook 設定 ID |
project_name | 觸發事件的專案名稱 |
scope | 事件來源類型：site / lottery / poll / form / newsletter / personality_test |
version | Payload 版本號 |
created_at | 事件觸發時間（ISO 8601） |
data | 該事件的詳細資料（見下方各事件說明） |
專案層級事件的 data 中帶有 project_id
元件層級事件的 data 中帶有 component_id
Payload 欄位參考
專案層級（site.*）
site.save、site.publish_update、site.close、site.publish 的 data 欄位相同：
欄位 | 說明 |
|---|---|
publish_url | 該專案的發佈網址 |
edit_at | 最後編輯時間 |
範例 Payload：
{
"project_name": "春季活動頁",
"scope": "site",
"event": "site.publish",
"version": "1",
"created_at": "2025-04-01T10:30:00Z",
"data": {
"project_id": "proj_abc123",
"publish_url": "https://example.weba.tw/s/abc123",
"edit_at": "2025-04-01T10:29:58Z"
}
}抽獎事件
lottery.add_award
欄位 | 說明 |
|---|---|
lottery_title | 抽獎活動名稱 |
lottery_id | 抽獎活動 ID |
award_title | 獎品名稱 |
award_id | 獎品 ID |
award_is_award | 是否為獎品（布林值） |
award_nr_number | 獎品數量 |
award_nr_chance | 中獎機率 |
award_image_url | 獎品圖片網址 |
lottery.winner
欄位 | 說明 |
|---|---|
lottery_title | 抽獎活動名稱 |
lottery_id | 抽獎活動 ID |
submitted_at | 中獎時間 |
award_title | 獎品名稱 |
award_id | 獎品 ID |
award_nr_number | 原始獎品數量 |
award_remaining | 剩餘獎品數量 |
login_id | 中獎者識別碼 |
login_email | 中獎者 email |
white_list | 是否來自白名單 |
lottery.form_submit
欄位 | 說明 |
|---|---|
lottery_title | 抽獎活動名稱 |
lottery_id | 抽獎活動 ID |
form_id | 表單 ID |
form_title | 表單標題 |
fields | 填寫欄位陣列（見 fields 欄位說明） |
submitted_at | 填寫時間 |
lottery.empty_award
欄位 | 說明 |
|---|---|
lottery_title | 抽獎活動名稱 |
lottery_id | 抽獎活動 ID |
award_title | 已空的獎品名稱 |
award_id | 已空的獎品 ID |
投票事件
poll.new_submit
欄位 | 說明 |
|---|---|
form_id | 投票表單 ID |
title | 投票標題 |
started_at | 開始填寫時間 |
submitted_at | 送出時間 |
fields | 填寫欄位陣列 |
表單事件
form.new_submit
欄位 | 說明 |
|---|---|
form_id | 表單 ID |
title | 表單標題 |
started_at | 開始填寫時間 |
submitted_at | 送出時間 |
fields | 填寫欄位陣列 |
電子報事件
newsletter.new_subscribe
欄位 | 說明 |
|---|---|
newsletter_id | 電子報 ID |
submitted_at | 訂閱時間 |
name | 訂閱者姓名 |
訂閱者 Email |
心理測驗事件
personality_test.new_submit
欄位 | 說明 |
|---|---|
quiz_id | 測驗 ID |
title | 測驗標題 |
fields | 作答欄位陣列 |
result | 測驗結果 |
fields 欄位說明
含有表單填寫資料的事件（lottery.form_submit、poll.new_submit、form.new_submit、personality_test.new_submit）中，fields 是一個 JSON 陣列，不是字串。
每個陣列元素的常見欄位：
欄位 | 說明 |
|---|---|
id | 題目 ID |
name | 題目名稱 |
type | 題目類型 |
value | 回答值（格式化後） |
raw_values / rawValues | 原始回答值（陣列） |
注意： raw_values（snake_case）與 rawValues（camelCase）在不同事件中使用不同命名。personality_test.new_submit 使用 rawValues；其餘事件使用 raw_values。建議伺服器端同時處理兩種 key，或根據事件類型分支判斷。
驗證與簽章
WEBA 使用 HMAC-SHA256 對每筆 Webhook 請求進行簽章，透過 X-Weba-Signature-256 header 傳遞。
簽名原文組成方式：
{X-Weba-Timestamp}.{raw request body}例如：
2026-04-30T05:58:50.015Z.{"event":"site.publish",...}建議的驗證流程：
取得建立時保存的 Webhook Secret
從 header 取出 X-Weba-Timestamp 的值
將 timestamp + “.” + raw body 作為訊息，以 Secret 為 key 計算 HMAC-SHA256
去除 X-Weba-Signature-256 的 sha256= 前綴，再與計算結果比對
不一致時拒絕該請求，回傳非 200 狀態碼
Node.js 範例：
const crypto = require('crypto');
function verifySignature(secret, rawBody, timestampHeader, signatureHeader) {
const message = timestampHeader + ‘.’ + rawBody;
const expected = crypto
.createHmac(‘sha256’, secret)
.update(message)
.digest(‘hex’);
const received = signatureHeader.replace(‘sha256=’, ”);
return crypto.timingSafeEqual(
Buffer.from(expected, ‘utf8’),
Buffer.from(received, ‘utf8’)
);
}
請使用 timingSafeEqual 比對，避免 timing attack。rawBody 必須是原始 bytes，不可先 parse 後再序列化，否則簽章會不吻合。
失敗與重試機制
規格 | 說明 |
|---|---|
成功條件 | HTTP 回應碼 200 |
最大重試次數 | 8 次 |
重試間隔 | 遞增延遲（指數退避） |
單次 Timeout | 5 秒；超過視為失敗 |
重試耗盡後的行為：
若 8 次重試全部失敗，WEBA 會自動刪除該 Webhook，以防止無效請求持續累積。
恢復方式：
修復接收端（確認 URL 可由外部存取、伺服器回傳 200）
重新至 Webhook 管理 新增 Webhook
妥善保存新的 Webhook Secret
錯誤處理規格
狀況 | 回應 |
|---|---|
事件不支援或事件值無效 | 400 event_not_supported |
請求超出頻率限制 | 429 too_many_requests |
建立時 URL 格式無效 | Webhook 仍會建立，但 toggle 預設為關閉 |
常見問題
建立成功後，下一步怎麼做？
複製並保存 Webhook Secret
在你的系統實際觸發一次事件
到 查看紀錄 確認：
是否出現傳送紀錄
HTTP 回應碼 是否為 200
請求 與 回應 內容是否符合預期
傳送失敗怎麼辦？
先到 傳送紀錄 檢查 HTTP 回應碼、回應 內容與 嘗試次數，再對應以下方向排查：
症狀 | 可能原因 |
|---|---|
沒有收到任何請求 | URL 設定錯誤，或接收端不對外開放 |
回應碼非 200 | 接收端程式有錯誤，或簽章驗證邏輯不正確 |
簽章驗證失敗 | Secret 遺失或用錯；確認是否對 raw body 計算 HMAC |
嘗試次數顯示 8 / 8 | 即將或已被自動刪除，需重新建立 Webhook |
Webhook 被自動刪除後怎麼辦？
修復接收端問題後，重新於 Webhook 管理 新增即可。自動刪除期間遺失的事件資料無法補送，建議接收端確認穩定後再重新啟用。
可以用手機設定 Webhook 嗎？
手機版僅支援查看 Webhook 管理 列表，無法新增或編輯。請使用桌機版後台操作。
如何避免重複處理同一筆事件？
每筆請求的 X-Weba-Delivery header 都帶有唯一識別碼，建議接收端記錄已處理過的 delivery ID，以防同一事件因重試被處理多次。