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 日。