---
{
  "id": "platform.trigger.events-and-scopes",
  "topic": "trigger",
  "title": "Trigger 事件、scope 與 Webhook 關係",
  "locale": "zh-TW",
  "version": "2026-08-31",
  "summary": "Trigger 的 source、event 與 scope 受 action registry 限制；外部 request 必須先由 Webhook 接受，Trigger 才能看到 webhook.received。",
  "content": "公開 action registry 目前只提供 `kanban`、`notebook`、`webhook` 三種 source types。service 內部雖有 calendar、form、mind-map 支援，在這些值正式出現在 `ActionDefinition.input_schema` 前，不得對 Agent 宣告。\n\n公開 event values 是 `card.created`、`card.updated`、`card.deleted`、`card.moved`、`card.moved_into_column`、`card.moved_out_of_column`、`column.cleared`、`board.all_done`、`note.created`、`note.updated`、`note.deleted`、`webhook.received` 與 `*`。wildcard 代表該已設定 source 的任一受支援事件，不會把 Trigger 變成任意 event bus。\n\n由使用者透過 REST 或 web 建立的 Notebook triggers 另外支援 `note.archived` 與 `note.unarchived`。這兩個 service events 在 v1 刻意不開放給 Agent action registry；封存生命週期自動化應使用 web Trigger form。\n\nKanban scope 必須有 `boardId`，可再以 `cardId` 或 `columnId` 其中一項縮小範圍，兩者不可共存。Notebook scope 必須有 `notebookId`，可加 `noteId`。Webhook scope 只能包含 UUID `webhookId`。建立或更新該 Webhook-backed Trigger 時，此 Agent 也必須對 Webhook 有明確 `read` 或 `write` grant；拒絕會回 not found。unknown keys 會 fail closed；ID 必須是 owner 可存取的資源，最終依 runtime validation。\n\nWebhook 負責 inbound endpoint、HMAC/replay 驗證、secret rotation 與 payload retention。request 通過接收後，Trigger 才能監聽 `webhook.received`。若需求同時包含 endpoint 與後續 Agent task，選 Webhook + Trigger；驗證失敗或被拒絕的 inbound request 不能描述成 Trigger fire 成功。\n",
  "aliases": [
    "sourceType",
    "sourceScope",
    "eventType",
    "卡片移動事件",
    "筆記事件",
    "webhook received",
    "wildcard event"
  ],
  "tags": [
    "trigger",
    "event",
    "scope",
    "webhook"
  ],
  "relatedActions": [
    "arinova.trigger.create_trigger",
    "arinova.trigger.update_trigger",
    "arinova.webhook.create_webhook"
  ],
  "relatedActionPrefixes": [],
  "url": "https://docs.arinova.ai/zh-tw/kb/trigger/events-and-scopes/"
}
---

公開 action registry 目前只提供 `kanban`、`notebook`、`webhook` 三種 source types。service 內部雖有 calendar、form、mind-map 支援，在這些值正式出現在 `ActionDefinition.input_schema` 前，不得對 Agent 宣告。

公開 event values 是 `card.created`、`card.updated`、`card.deleted`、`card.moved`、`card.moved_into_column`、`card.moved_out_of_column`、`column.cleared`、`board.all_done`、`note.created`、`note.updated`、`note.deleted`、`webhook.received` 與 `*`。wildcard 代表該已設定 source 的任一受支援事件，不會把 Trigger 變成任意 event bus。

由使用者透過 REST 或 web 建立的 Notebook triggers 另外支援 `note.archived` 與 `note.unarchived`。這兩個 service events 在 v1 刻意不開放給 Agent action registry；封存生命週期自動化應使用 web Trigger form。

Kanban scope 必須有 `boardId`，可再以 `cardId` 或 `columnId` 其中一項縮小範圍，兩者不可共存。Notebook scope 必須有 `notebookId`，可加 `noteId`。Webhook scope 只能包含 UUID `webhookId`。建立或更新該 Webhook-backed Trigger 時，此 Agent 也必須對 Webhook 有明確 `read` 或 `write` grant；拒絕會回 not found。unknown keys 會 fail closed；ID 必須是 owner 可存取的資源，最終依 runtime validation。

Webhook 負責 inbound endpoint、HMAC/replay 驗證、secret rotation 與 payload retention。request 通過接收後，Trigger 才能監聽 `webhook.received`。若需求同時包含 endpoint 與後續 Agent task，選 Webhook + Trigger；驗證失敗或被拒絕的 inbound request 不能描述成 Trigger fire 成功。