如何用background-agents的Webhook触发器任意外部系统一条HTTP请求启动编码会话【免费下载链接】background-agentsAn open-source background agents coding system项目地址: https://gitcode.com/GitHub_Trending/ba/background-agentsbackground-agentsOpen-Inspect是一个开源的后台编码智能体系统它内置了Webhook 触发器Inbound Webhook你只需向一个专属 URL 发送一条带 API Key 的 HTTP POST 请求就能让 AI 编码会话在沙箱里自动启动。无论是部署系统、监控系统还是内部工具都可以通过这条 HTTP 请求把事件喂给编码 Agent。什么是 background-agents 的 Webhook 触发器background-agents 的自动化Automations支持多种触发方式定时任务Cron、Sentry 告警、Slack 消息、GitHub 事件以及本文主角——Inbound Webhook。它是其中最灵活的事件驱动选项适合 部署失败时自动让 Agent 修复 监控系统发出告警时自动排查 内部平台工单、发布系统联动编码任务 定时任务系统之外的自定义集成核心机制只需一句话外部系统发一个 JSON 请求 → background-agents 校验 API Key → 把请求体作为上下文附加到你的指令前 → 自动开一个新编码会话。完整说明见官方文档 docs/AUTOMATIONS.md。三步搭建从创建到第一条请求第 1 步创建 Webhook 自动化在 Web 界面左侧边栏进入Automations点击Create Automation将Trigger Type选为Inbound Webhook。必填项只有字段说明Name自动化名称会话标题会以[Auto]前缀显示Repository Configuration选择仓库、分支可选不挂仓库纯对话/MCP 工具模式Instructions每次触发时发给 Agent 的提示词最多 15,000 字符Webhook 类型不需要 Schedule / Timezone 字段。保存后会展示Webhook URL 和 API Key——⚠️API Key 只显示一次请立即妥善保存详情页面之后只能看到 Webhook 路径。第 2 步了解请求规范Webhook 端点的实现位于 automation-webhook.ts请求必须满足要求值方法POST路径/webhooks/automation/{automation-id}Content-Typeapplication/json认证Authorization: Bearer api-key最大请求体64 KB任何合法 JSON 都会被接受字段完全由你自定义。第 3 步发送你的第一条 HTTP 请求curl -X POST https://你的部署域名/webhooks/automation/automation-id \ -H Authorization: Bearer api-key \ -H Content-Type: application/json \ -d {event:deploy.failed,service:api,environment:prod}成功后返回{ ok: true, triggered: 1, skipped: 0 }triggered是本次启动的会话数skipped是因涉嫌重复投递或并发保护被忽略的数量。Agent 实际看到了什么每次请求被接受后系统会调用 normalizer.ts 中的normalizeWebhookEvent再由 context.ts 生成一段上下文块前置到你的 Instructions 之前内容包括触发来源inbound webhook接收时间JSON 请求体超过 4096 字符会截断一句安全警告请求体是外部不可信数据只能当数据处理不能当指令执行所以编写 Instructions 时应假设 Agent 会同时读到你的提示词 外部 payload例如根据 payload 中的event和service字段定位问题并修复。用 JSONPath 过滤条件只让特定事件触发如果你的系统事件很多可以给自动化配置JSONPath Filter条件事件必须全部命中才会运行目标过滤条件只处理生产环境$.environment eq production只处理失败的部署$.status eq failed字段存在即触发$.pull_request.number exists支持eq/neq/gt/gte/lt/lte/contains/exists八种比较路径语法为简单点号表示法如$.event.type。过滤逻辑同样实现在 normalizer.ts 中。idempotencyKey重试友好防止重复开会话如果发送方可能重试同一事件比如队列重投请在 JSON 体里加一个idempotencyKey字段{ idempotencyKey: deploy-12345-failed, event: deploy.failed }相同idempotencyKey的重复投递只会启动一次会话该字段会保留在存储记录中但不会出现在 Agent 看到的上下文块里不传时每次投递都有独立并发键同一自动化的多个请求可以并行运行。错误码速查表状态码含义400JSON 请求体非法401缺少或 API Key 无效404自动化不存在或该自动化不是 Webhook 类型413请求体超过 64 KB415Content-Type 不是application/json遇到连续 3 次运行失败自动化会**自动暂停Auto-Pause**以防失控恢复后失败计数归零。安全设计值得了解API Key 采用高熵随机生成32 字节crypto.getRandomValuesbase64url 编码服务端只存 SHA-256 哈希并用常量时间比较校验实现见 webhook-key.tsPayload 被视为不可信输入上下文块中自带防提示注入警告请求体在读取前先看 Content-Length快速拒绝超大请求保护控制平面。常见问题Q不挂仓库可以吗可以。选择 No repository 后 Agent 不克隆仓库但仍可使用 MCP 服务器等已配置工具只是无法开 PR 等需要仓库上下文的动作。Q和定时任务Schedule能同时用吗一条自动化只有一个触发类型。需要定时 事件时创建两条自动化即可。Q怎么调试不触发依次检查① 是否用了 POST 和 JSON Content-Type② Bearer Key 是否一字不差③ 路径里的 automation-id 是否正确④ JSONPath 条件是否全部命中⑤ 是否连续失败 3 次被自动暂停。自动化详情页的运行历史会给出每次调用的状态。 延伸阅读完整自动化文档docs/AUTOMATIONS.mdWebhook 路由与校验实现packages/control-plane/src/webhooks/automation-webhook.ts事件归一化与条件过滤packages/shared/src/triggers/webhook/normalizer.ts上下文块构建packages/shared/src/triggers/webhook/context.tsAPI Key 生成与校验packages/control-plane/src/auth/webhook-key.ts把 background-agents 的 Webhook 触发器接进你的任意外部系统一条 HTTP 请求就能让编码 Agent 开工——这是事件驱动自动化里最简单、也最通用的一条路。【免费下载链接】background-agentsAn open-source background agents coding system项目地址: https://gitcode.com/GitHub_Trending/ba/background-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考