# 接收事件并触发自动化任务

要让第三方事件启动智能体，需要同时配置四项内容：支持回调的通道实例、公开回调地址、`callback` 类型自动化任务和回调规则。任意一项缺失，都不会形成历史记录。

## 开始之前

请先完成：

1. [配置并测试通道实例](manage-channels.md)，保存 `credential_ref` 和 `callback_path`；
2. [创建自动化任务](../automation/manage-tasks.md)，将 `trigger.mode` 设为 `callback`；
3. 从第三方平台文档确认其地址验证、签名、重试和事件字段。

企业微信、GitHub、飞书和 Slack 可以使用公开事件回调入口。其他通道实例可能用于工具凭据或系统智能体配置，不应据此推断它们支持入站事件。

## 1. 配置公开回调地址

通道实例返回的 `callback_path` 形如：

```text
/newmoi/callbacks/{provider}/{workspace_id}/{credential_ref}
```

将它与当前 Product API 的协议和主机组合后，配置到第三方平台。公开入口接受 Provider 的地址验证和事件请求，不使用 `X-API-Key`；平台会根据路径中的工作区和凭据引用找到通道配置，再按 Provider 协议验证签名和解析事件。

不要自行缩短路径、替换 `credential_ref`，也不要把第三方 Secret 放进 URL。

## 2. 创建回调规则

下面把飞书消息事件路由到一个回调类型自动化任务：

```bash
curl -X POST \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/callback-rules" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "feishu",
    "credential_ref": "<CREDENTIAL_REF>",
    "name": "feishu-message-to-support-agent",
    "description": "Route received messages to the support automation task.",
    "enabled": true,
    "priority": 100,
    "match": {
      "event_types": ["im.message.receive_v1"]
    },
    "target_type": "agent_automation_task",
    "target_config": {
      "automation_task_id": "<AUTOMATION_TASK_ID>"
    },
    "stop_after_match": true
  }'
```

`provider` 和 `credential_ref` 必须与通道实例一致。`match` 可以按资源类型、事件类型、事件动作或字段相等条件筛选；这些值来自 Provider 解析后的事件，不同 Provider 不能共用一套事件名称。

## 3. 验证端到端链路

从第三方平台发送一个可识别的测试事件，然后按顺序检查：

1. Provider 后台是否显示投递成功；
2. 通道实例和凭据是否仍处于可用状态；
3. 回调规则是否启用，Provider、凭据引用和匹配条件是否正确；
4. 目标自动化任务是否为活动状态且触发模式为 `callback`；
5. 是否出现 `trigger_type=callback` 的历史记录；
6. 运行是否进入终态，并能读取结果或错误。

不要用公开回调入口的 HTTP 接收成功代替业务成功判断。事件可能已接收，但没有规则匹配，或者目标任务运行失败。

## 规则优先级和停止条件

多条规则可能匹配同一事件。`priority` 决定评估顺序，`stop_after_match=true` 表示命中后停止继续匹配。建立多条规则前先定义清楚是否允许一个事件启动多个任务，避免重复副作用。

更新规则时必须携带当前 `version`。若发生版本冲突，重新读取规则并合并修改。停用规则适合临时停止路由；删除规则前应保留所需的配置记录。

## 下一步

- [运行自动化任务并读取结果](../automation/run-tasks.md)
- [查询通道与回调 API](api-reference.md)
- [查看状态码与错误码](../../common/status-error-codes.md)