UnifyPort Webhook 事件篩選：該用 subscribed_events 還是萬用字元？
單一用途的正式環境處理器應明確列出 subscribed_events；若端點是完整事件收集器，或你仍在確認工作流程需要哪些事件，則使用 ["*"]。萬用字元涵蓋所有公開標準事件，但不包含內部原始事件。對訊息收件匣而言，可以先訂閱 message.received，只有在同一服務也負責連線健康狀態時，才加入帳號生命週期事件。
重點整理
subscribed_events接受精確的公開事件名稱，或單獨使用["*"]訂閱完整公開目錄。- 建立或更新端點時，未知事件名稱會遭到拒絕。
- 訂閱某事件不代表每個平台都會送出它，仍須查看平台事件矩陣。
message.received可能代表入站或出站訊息，必須檢查data.message.direction。- 事件篩選、HMAC 簽章、成功確認與重試是彼此獨立的控制項。
subscribed_events 控制什麼
UnifyPort 會將 subscribed_events 選取的事件，透過 HTTP POST 傳送到 Webhook 端點。標準封套固定包含 id、type、provider、account_id、occurred_at，以及依事件而異的 data。可用名稱與資料格式請見標準事件目錄。
最小的入站訂閱如下：
{
"subscribed_events": ["message.received"]
}處理器仍需要判斷方向：
if (
event.type === 'message.received' &&
event.data?.message?.direction === 'inbound'
) {
await storeInboundMessage(event);
}這個事件表示連線中的 messaging account 觀察到一則訊息，並不保證一定是入站訊息。
萬用字元寫法為：
{
"subscribed_events": ["*"]
}請把它當成完整選擇，不要將 "*" 與具名事件混在同一陣列。它會選取所有公開標準事件，但不會公開內部原始事件。
三種實用篩選模式
1. 僅處理入站收件匣
適合只負責儲存及分派客戶來訊的服務：
{
"subscribed_events": ["message.received"]
}只處理 data.message.direction 為 inbound 的紀錄。之後若需要編輯、刪除、表情回應或回條，再加入相對應的精確事件名稱，並先定義它們如何更新既有狀態。
2. 入站收件匣加帳號健康狀態
若同一服務也要顯示授權失效或執行階段斷線，可使用：
{
"subscribed_events": [
"message.received",
"account.status.updated",
"account.started",
"account.auth.required",
"account.auth.succeeded",
"account.auth.failed"
]
}不要把每個狀態事件都當成重新啟動指令。先同步 auth_status 與 runtime_status，再次查核帳號後再動作。messaging account 執行階段復原手冊說明何時應 refresh、reconnect、start 或重新驗證。
3. 完整事件收集器
若端點是統一的事件接收邊界，後續才分派給不同消費者，請用 ["*"]。WhatsApp、Telegram、LINE、TikTok、Zalo 與 X 可以共用一個具簽章的佇列，再分別處理訊息、回條、群組及帳號狀態。
萬用字元收集器仍需為未來新增的公開事件準備預設分支：安全儲存封套並回覆成功，無法辨識的類型送往可觀察的隔離佇列，不要假設每個事件都是訊息。
使用明確篩選條件建立端點
實際 API 路由是 POST /v1/webhook-endpoints。以下請求會建立啟用簽章的有效端點，接收訊息與帳號狀態：
curl -X POST https://api.unifyport.ai/v1/webhook-endpoints \
-H "X-Api-Key: $UNIFYPORT_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"url\": \"https://inbox.example.com/webhooks/unifyport\",
\"status\": \"active\",
\"subscribed_events\": [
\"message.received\",
\"account.status.updated\",
\"account.auth.required\"
],
\"signing_secret\": \"$WEBHOOK_SIGNING_SECRET\",
\"retry_policy\": { \"max_attempts\": 3 }
}"欄位定義以建立 Webhook 端點參考為準。retry_policy.max_attempts 計算首次傳送之後的重試次數；文件預設值 3 代表首次請求後最多再試三次，允許範圍為 0 至 5。
日後要修改篩選條件時，使用文件中的 PATCH /v1/webhook-endpoints/{endpoint_id} 並送出更新後的 subscribed_events；建立與更新採用相同的名稱驗證規則。
將篩選與傳輸安全分開
事件篩選決定 UnifyPort 傳送什麼；signing_secret 決定傳送是否包含 X-Device-Timestamp 與 X-Device-Signature。啟用簽章時，請在解析 JSON 前，以時間戳記、句點及原始請求本文計算十六進位 HMAC-SHA256 並驗證。
任何 2xx 都代表成功確認。連線錯誤及 HTTP 408、429、5xx 可依設定重試；其他 4xx 不會重試。傳送採至少一次語意，因此普通事件的重送必須以冪等方式處理。
完整實作請參考Webhook 傳送與簽章驗證，以及更深入的HMAC 重送防護與冪等教學。
加入事件名稱前先確認平台支援
公開目錄定義合法事件名稱，但各平台解析器並不會映射所有事件。message.received 與重要帳號事件的涵蓋較廣；回條、訊息編輯、對話變更與群組更新則因平台而異。
讓消費者依賴某事件前，先查看各平台 Webhook 事件差異。有效訂閱只是篩選器，不保證上游帳號一定產生該事件。
若你建置的是自動化流程而非通用收集器，可接著閱讀n8n WhatsApp 簽章 Webhook 教學，了解為何驗證與可靠寫入應位於 AI 工作流程之前。
限制與取捨
明確事件清單可降低雜訊並釐清責任，但新增需求時必須先更新設定。萬用字元不易漏掉新的公開事件，卻要求消費者能處理更多類型與未來新增內容。
UnifyPort 沒有通用 REST 訊息歷史讀取 API，也不保證補送所有遺漏資料。應先註冊接收端，再連接正式環境的 messaging account，並在事件抵達時保存需要的資料。有限的 WhatsApp 歷史同步只協助連續性，不能取代自有事件儲存。
UnifyPort 是非官方介面。若專案必須採用官方平台認證流程，或需要文件矩陣以外的平台專屬能力，應選用相應平台的官方 API。
常見問題
該用 message.received 還是 ["*"]？
專用收件匣處理器使用 message.received；需要儲存並分派所有公開標準事件的通用收集器使用 ["*"]。
message.received 是否只有入站訊息？
不是。只處理來訊時，請確認 data.message.direction 等於 inbound。
可以訂閱平台內部事件嗎？
不行。subscribed_events 僅接受公開標準名稱，萬用字元也不會提供內部原始事件。
事件名稱拼錯會怎樣？
建立或更新請求會拒絕未知名稱，不會默默保存永遠無法匹配的設定。
["*"] 是否保證每個平台都有全部事件？
不保證。它選取全部公開標準類型，但實際支援與上游可用性仍因平台而異。
下一步
開啟建立 Webhook 端點參考，選擇上述三種篩選模式之一，並在連接正式 messaging account 前註冊接收端。
資料來源
查核日期：2026 年 8 月 19 日。