跳到正文
Ankole

Webhook 委托

面向 AI Agent:本页的 Markdown 版本位于 https://ankole.agentbull.com/zh-Hans-CN/docs/webhook-delegations/index.md,全站文档索引位于 https://ankole.agentbull.com/zh-Hans-CN/llms.txt。

外部事件可通过连接器订阅或普通回调端点进入 Ankole。两种方式都先持久化投递结果,再确认接收,并可通过绑定交给 Agent 或 Applet 任务处理。

选择事件源

GitHub 仓库或组织事件、飞书审批或日历变化等受支持的订阅,在 Pod「外部连接」页面管理。管理员配置应用,需要个人授权的订阅由成员连接自己的账户。选择资源并创建订阅后,可查看订阅状态;控制面负责在上游创建、接管和删除订阅。失败会保留可见状态,并提供重试操作。

其他服务能够向指定 URL 发送 POST 时,可使用普通回调。在 Applet「自动化」面板为任务创建 Webhook,选择 standing 或 one_shot,并设置有效期。回调 URL 只在创建时显示一次,应复制到发送端后测试。需要恢复 Agent 会话的回调仍可通过 create-webhook-cli --help 所述命令创建。

投递与归属

one_shot 端点只接受首次匹配投递,后续投递不会再启动执行。standing 端点持续接收,直到暂停、撤销或过期。消费者应能处理上游重复事件;执行有实际影响的操作前,应确认来源系统的当前状态。

任务持有的端点直接触发 Applet Action,不要求 Agent 会话或任务提示词。处理函数读取 ctx.signal,「自动化」面板将回执关联到运行状态、输入、结果和日志。个人端点遵循任务所有者的权限,团队端点遵循页面权限。删除任务会清理其持有的端点;解除共享连接器订阅中的一个消费者,不会删除其他消费者仍在使用的订阅。

管理与排查

暂停会停止接收但保留配置,可在需要时恢复;撤销或删除用于停用回调。撤销 Ankole 普通端点不会删除发送方单独配置的 Webhook。连接器管理的订阅则通过自身的远端协调流程清理。

普通回调需要公网 HTTPS 转发 /webhooks/v1/event-callbacks/*,连接器回调需要转发 /webhooks/connectors/*。应妥善保存回调 URL。Ankole 只保存其摘要,并在控制面日志中隐藏 URL;反向代理也应隐藏它。持有 URL 只表示可以提交事件,不代表事件内容可信。

失败时先检查发送方记录、端点状态与有效期、订阅授权,再检查投递回执和运行记录。已接收但执行失败的事件需要修复执行原因;重复发送不能解决缺少授权或输入错误。

参阅自动化任务和信号。