Atlassian Forge Web Trigger 生命周期 API 上线：创建、轮换与删除如何接入服务

以前，Forge 容器服务要动态管理 Web Trigger URL，通常要把 CLI 或 Forge API 调用放在应用外部。Atlassian 在 2026 年 8 月的 Forge 变更中补上了 Container Services 的 Web Trigger 生命周期 REST API：容器可以自己创建、列出和删除 URL，部署流程不必再依赖一台额外的管理机。

这次更新解决的是“谁来管理 URL”的问题，不是“URL 自动获得认证”的问题。接入时先把创建、查询、删除做成可回收的生命周期，再在 Web Trigger handler 内校验调用方。

这次 Forge 更新改变了哪一层

官方变更日志给出的范围很窄，也很实用：新增的是 Forge Container Services REST API，提供三个端点，能力与 @forge/api 和 Forge CLI 的 Web Trigger 管理操作对齐。它适合容器在启动、租户配置变更或下线时自行管理入口；并没有改变 Web Trigger 的请求模型和安全默认值。

因此，迁移时不要把它当成一个新的业务回调协议。业务函数仍然要从请求中读取 method、path、headers、body 等字段，并自行决定返回的 statusCode。

先用 POST 创建或复用一个 URL

最小请求只需要 Web Trigger 模块的 key。如果容器重启后希望继续使用已有入口，可以不强制创建；如果正在做轮换，则把 forceCreate 设为 true，并把新旧 URL 的切换留在应用自己的配置流程里。

POST /forge/webtrigger/url
Content-Type: application/json

{
  "key": "order-events",
  "forceCreate": false
}

成功响应是 200，并返回一个 url 字段。生产代码应把这个完整 URL 当作敏感的入口资产处理：写入受保护配置或密钥系统，不要直接打进普通业务日志。

用 GET 做启动自检，用 DELETE 收口旧入口

容器服务完成部署后，可以调用 GET 端点确认应用当前仍有哪些 Web Trigger URL。返回数组中的 key 和 url 很适合与配置中心中的期望集合比较：缺少的是创建问题，多出来的是遗留入口。

GET /forge/webtrigger/urls

[
  {"key":"order-events","url":"https://install-uuid.webtrigger.atlassian.app/public/webtrigger-url-uuid-789"}
]

删除操作要求传入创建时拿到的完整 URL，而不是只传模块 key。官方 REST 文档给出的成功状态是 204 No Content。轮换流程可按“创建新 URL、让调用方切换、验证新入口、删除旧 URL”的顺序执行；如果先删除旧地址，再更新外部调用方，短时间内一定会出现不可用窗口。

DELETE /forge/webtrigger/url?url=

别把生命周期 API 当成鉴权方案

Forge 官方 Web Trigger 文档明确说明，URL 默认不由平台认证。外部系统可以带 HMAC 签名、Bearer token 或其他约定，但校验动作必须写在被调用的 handler 中。对于订单回调这类入口，至少要检查时间戳、签名、重放窗口和业务事件 ID；返回 200 也应放在校验和幂等处理之后。实际安全边界可以压缩成“公开 URL → handler 鉴权 → 响应状态”三段。

还要注意 Web Trigger 的上下文限制：官方文档指出，调用不会附带 Atlassian 用户信息，因此不要假设可以在这里使用需要用户身份的 asUser 调用。需要 Atlassian 身份时，应重新设计调用链，而不是仅仅给 URL 增加一个参数。

接入时建议保留的最小验收清单

• manifest 中的 Web Trigger key 与 POST 请求的 key 一致，且函数已部署。
• 容器启动后 GET 返回的 URL 集合与配置中心预期一致。
• 轮换先创建新 URL，再切换调用方，最后 DELETE 旧 URL，并记录每一步结果。
• handler 能拒绝缺少签名、过期签名和重复事件，不能只依赖 URL 隐蔽性。
• 删除后用受控测试请求确认旧地址不再调用函数，同时保留 204 响应记录。

相关问题

POST 的 forceCreate 应该一直设为 true 吗？

不建议。稳定运行场景优先复用已有 URL，只有明确做轮换、隔离环境或恢复遗留状态时才强制创建，并同步保存新旧映射。

GET 查询到多个相同 key 怎么处理？

不要静默挑一个。先把 URL 与安装上下文、环境和配置中心记录对比，再决定保留哪一个，其余入口按轮换流程回收。

删除 URL 后还能恢复吗？

原 URL 不能继续调用底层模块。需要恢复时重新创建入口，并让外部调用方更新到新的完整 URL。

把这次更新落到部署流程里

对 Forge Container Services 来说，新增 API 的价值在于把 Web Trigger 从“部署人员手工生成的一串地址”变成应用可以盘点、轮换和回收的运行资产。先实现幂等创建和启动自检，再补上带签名的 handler 与旧地址回收，才能真正把这项更新变成可运维的能力。