osFoundry / Platform
入站 webhook
为每个应用或工作区提供一个用于接收事件的 URL。签名校验默认内置。
简介
入站 Webhook 为 osFoundry 提供了一个面向外部世界的接收地址。你生成一个绑定到特定应用、实例和频道的令牌，osFoundry 会返回一个位于 /api/v1/webhooks/inbound/{id} 下的专属 URL。外部系统（Stripe、GitHub、Zapier、CI 流水线，或你自己的后端）将 JSON 以 POST 发送到该 URL，事件便落入你所选的实时频道，你的聊天、智能体和应用可以在那里对它作出响应。无需轮询，也无需另外运行一台集成服务器：这个端点本身就是集成。\n\n签名验证是内建的，而非事后加装。每个令牌都带有一个 HMAC-SHA256 签名密钥，仅在生成时显示一次。发送方对载荷计算签名，并通过 X-OsFoundry-Signature 请求头传入；osFoundry 会在每次请求时校验它，并拒绝任何未签名或在传输途中被篡改的内容。当你需要为某个发送方更换密钥时，轮换密钥会打开一个 7 天的宽限窗口，在此期间旧密钥仍然有效，因此轮换绝不会丢掉正在传输的事件。吊销令牌是即时的：端点会立刻开始返回 401，这正是应对密钥泄露或下线集成的快速通道。\n\n由于这一切都在 osFoundry 的 BYOK 桌面工作区内运行，一条入站事件可以触发你早已在用的那些智能体、应用和知识，既没有按席位计费的集成税，你的数据也不会绕经第三方中间人。每个令牌都会记录最后使用时间和过去 24 小时的请求数，让你看清哪些发送方处于活跃状态；平台还保留最近 100 条入站请求以供重放，这让 Webhook 调试从靠猜测变为重新运行真实的载荷。
主要功能
- 为每个应用、实例和频道生成专属的接收 URL：外部系统将 JSON 事件直接 POST 到位于 /api/v1/webhooks/inbound/{id} 下的该端点
- 每次请求都会依据 X-OsFoundry-Signature 请求头中的 HMAC-SHA256 签名进行验证，未签名或被篡改的载荷会在抵达你的频道之前被拒绝
- 轮换签名密钥时带有 7 天宽限窗口，其间旧密钥仍可通过验证，让你在不丢失事件的情况下为发送方更换密钥
- 即时吊销令牌：一经吊销，端点便返回 401，切断已泄露或已停用的发送方
- 按令牌查看最后使用时间和 24 小时请求数，当你需要调试某次投递时，可在触发器设置中重放最近 100 条入站请求
使用场景
- 接入 Stripe 的开发者：生成一个绑定到计费频道的令牌，将 Stripe 的 webhook 指向该 URL，让 osFoundry 在任何 HMAC 签名不匹配的 POST 抵达智能体之前将其拒绝
- 遭遇密钥泄露的运维工程师：吊销受影响的令牌以立即返回 401，并生成一个新令牌，同时不会中断向工作区供数的其他集成
- 接入 CI 流水线的自动化搭建者：将构建状态事件 POST 到一个频道，由智能体在此分诊失败，并借助最近 100 条请求的重放来调试载荷结构
常见问题
osFoundry 如何验证一条入站 Webhook 是真实的？
每个入站令牌都有一个 HMAC-SHA256 签名密钥。发送方对请求体计算签名，并通过 X-OsFoundry-Signature 请求头发送，osFoundry 会在每次请求时重新计算并比对。签名缺失或无效的请求会被拒绝，因此只有持有密钥的系统才能向你的频道发布内容。该密钥在生成时仅显示一次，请当时就妥善保存，因为之后不会再次显示。
当我轮换或吊销令牌时，正在传输的事件会怎样？
轮换会给你一个 7 天的宽限窗口，其间新旧密钥都能通过验证，因此你可以更新每一个发送方，而不会在切换期间丢失事件。吊销在设计上则恰恰相反：端点会立即返回 401，当场切断发送方，这正是密钥泄露或集成下线时你所需要的。
我是所有场景共用一个 Webhook URL，还是可以按范围划分？
每个令牌都绑定到特定的应用、实例和频道，并在 /api/v1/webhooks/inbound/{id} 下生成自己的 URL。这意味着某个发送方无法向未获授权的频道发布内容，你也可以吊销或轮换单个集成而不影响其他集成。每个令牌还会报告最后使用时间和 24 小时请求数，让你分辨出哪些端点确实在接收流量。