用 Trigger 接收第三方事件

Trigger 订阅关注某个终端用户的连接账号，把新的第三方事件作为 trigger.message 发送到你的项目 Webhook。例如用户的 Google Sheets 新增了一行、Gmail 收到新邮件，或 Stripe 付款状态变了，你的后端会收到一条对应的事件。

订阅由 Connector 运行：轮询 provider、注册和接收 provider 的 webhook 都在 Connector 侧完成。你的后端负责创建订阅和处理收到的事件。

事件如何到达

推送类 Trigger 涉及两个地址：项目 Webhook 接收 Connector 发来的事件，第三方入站回调地址（push.callbackUrl）接收 provider 发来的事件。大部分回调地址由 Connector 自动注册；Slack、Microsoft Teams、飞书和 Intercom 需要管理员把它填到 provider 应用中。

准备工作

1. 按 Connector for SaaS 使用指南完成接入，让后端持有 Project API key，并保存每个用户的 connectedAccountId。
2. 创建项目 Webhook，eventTypes 包含 trigger.message，authTypes 包含要订阅账号的授权类型。Google 账号为 oauth2。一个 Webhook 可以接收项目内所有订阅的事件。
3. 让终端用户连接 Trigger 要读取的账号。

如果账号已路由到专用 Webhook，事件只会发往该 Webhook，上述条件改为对它检查。

创建或恢复订阅时，Connector 会检查 Webhook。没有匹配的 active Webhook 时，请求返回 trigger_delivery_unavailable。

第 1 步：选择 Trigger

列出已发布的 Trigger，并查看所需 Trigger 的配置 schema：

curl --silent --show-error \
  'https://connector.oomol.com/v1/saas/trigger-types/googlesheets.on_row_added' \
  -H "Authorization: Bearer $PROJECT_API_KEY"

GET /v1/saas/trigger-types 列出所有已发布的 Trigger，加 ?service=googlesheets 可按 provider 筛选。所有项目看到的目录相同。

第 2 步：创建订阅

下面的示例监听 Orders 工作表的新增行：

curl --silent --show-error \
  'https://connector.oomol.com/v1/saas/trigger-subscriptions' \
  -H "Authorization: Bearer $PROJECT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: orders-sheet-customer-1' \
  --data @- <<JSON
{
  "userId": "customer-1",
  "connectedAccountId": "$CONNECTED_ACCOUNT_ID",
  "triggerId": "googlesheets.on_row_added",
  "config": {
    "spreadsheetId": "<spreadsheet-id>",
    "sheet": "Orders"
  },
  "intervalSeconds": 300
}
JSON

请求时带上 Idempotency-Key，避免重试请求创建出第二个订阅。首次请求返回 201；用同一个 key 重放相同请求返回 200 和原订阅；同一个 key 用于不同请求返回 409。

把返回的 id 与用户、账号一起保存到数据库。也可以在 Console 中创建和管理订阅：打开项目后进入事件订阅。

接收事件

每个事件都以签名的 trigger.message 投递到项目 Webhook。先校验签名，再读取 envelope：

{
  "id": "evt_0199d2a8-4c1b-7e2f-8a3d-6b5c4d3e2f10",
  "type": "trigger.message",
  "version": 1,
  "createdAt": 1800000300000,
  "data": {
    "subscriptionId": "0199d290-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
    "triggerId": "googlesheets.on_row_added",
    "definitionVersion": 2,
    "externalUserId": "customer-1",
    "connectedAccountId": "0199d1f4-2e5f-7b61-8c72-9d0e1f2a3b4c",
    "providerConfigId": "0199d1a0-5f6e-7d8c-9b0a-1c2d3e4f5a6b",
    "service": "googlesheets",
    "payload": {
      "spreadsheetId": "<spreadsheet-id>",
      "sheetId": 0,
      "sheetTitle": "Orders",
      "rowNumber": 12,
      "row": { "Order ID": "A-1001", "Amount": 42 },
      "values": ["A-1001", 42]
    }
  }
}

data.payload 符合该 Trigger 的 eventSchema。用 subscriptionId 或 externalUserId 把事件路由给对应用户，并按 envelope 的 id 去重：同一事件在重试和不同 Webhook 之间保持相同的 id。

轮询类订阅的首次读取只记录当前位置，不会发送已有的行、邮件或记录。读取完成后，订阅的 initialized 变为 true，之后产生的事件会在后续读取中发送。

投递沿用项目 Webhook 的重试策略。同一事件可能多次到达；重试用尽或遇到不可重试的 4xx 时，投递以 failed 结束，可以在 Console 的投递记录或投递记录 API 中查看。每个 Webhook 同时最多有 5 个请求在发送；端点响应慢只会延后它自己的队列，不影响其他 Webhook。投递到达终态的事件保留 7 天。

管理订阅

订阅会返回 status、pauseReason、initialized、nextPollAt、lastSuccessAt、lastError 和 consecutiveFailures。推送类订阅还会返回 push.callbackUrl、push.setup（automatic 或 application）和 push.ready。删除订阅后不再读取新数据，删除前已记录的事件仍会投递。

订阅暂停时

Connector 无法安全继续时会暂停订阅，pauseReason 说明原因和处理方式：

provider 的临时错误不会导致暂停。Connector 会从 30 秒起退避重试，最长间隔 30 分钟，并在 lastError 和 consecutiveFailures 中记录最近状态。

用户重新连接同一个 provider 账号时，订阅照常运行。如果用户在同一 alias 下换成另一个 provider 账号，相关订阅会以 checkpoint_reset_required 暂停。

计费与团队余额

每个事件在首次成功投递到项目内任一 Webhook 时计费一次。读取、空读、重试、额外的 Webhook，以及最终投递失败的事件都不计费。

Trigger 需要团队余额足以覆盖 Connector 用量：

• 余额小于零时，创建或恢复订阅返回 402 insufficient_credit，读取和投递暂停。查看、调整间隔、暂停和删除仍然可用。
• 暂时无法核实余额时，上述请求返回 503 balance_unavailable，并带 Retry-After: 30。
• 投递受阻期间，每个项目最多缓冲 10,000 条待处理的推送事件。超出部分 Connector 仍会向 provider 正常应答，但不会保存，provider 也不会重发。确认欠费满 7 天后，待处理事件会过期，新的推送事件也会这样被丢弃，直到余额恢复。billing 视图会统计这两种情况。
• 团队充值后，读取和投递自动恢复。因其他原因暂停的订阅保持暂停。

订阅响应包含项目级 billing 摘要，其中有 state（allowed、insufficient_credit、balance_unavailable 或 unverified）、缓冲数量，以及被拒收和已过期事件的计数。列表响应在 meta.billing 中返回。unverified 表示团队余额还没有核实过，通常是因为项目还没有订阅；它不阻塞请求，创建订阅时会核实余额。

错误

可用的 Trigger

以 GET /v1/saas/trigger-types 返回的目录为准。

Provider 注意事项

轮询发送的是每次读取时可见的状态，两次读取之间的中间编辑不会逐条发送。同一 provider 账号、Base 或工作区下的多个订阅共享该 provider 的调用额度。

故障排查