ProfileClaw

Agent Webhooks

在正确时刻唤醒工作流,而不是无限轮询

webhook 真正有价值的时刻,是工作流需要在稍后的用户或系统事件发生后继续执行。它应该触发 fresh read 和确定性续跑,而不是变成神秘的第二事实源。

Format: AI-first docs
Source: DocsAgentsWebhooksPage
信息

如果工作流还不是真异步,就不要急着上 webhook。

起步阶段轮询更简单;只有当时机和连续性变成产品要求时,webhook 才会真正值得。

Webhook 职责

把事件当成触发器,而不是把它当成完整业务 payload。

Trigger

事件告诉 runtime:有变化发生,某条工作流可能需要恢复。

  • 用 profile 和 assessment 事件唤醒正确任务。
  • 在 runtime 里保持事件路由显式。
  • 不要把业务逻辑塞进投递层。

Re-fetch

收到投递后,先从正式 API 表面重新读取状态,再做动作。

  • 让 webhook 决定何时拉取,而不是盲信它本身。
  • 动作前重新读取 context 或更窄端点。
  • 让续跑保持幂等,重复投递也无害。

Operations

订阅必须可见、有归属,而且能被清理。

  • 记录哪条工作流拥有哪个 webhook URL。
  • 在模型循环之外审计订阅。
  • 流程退役时删除旧订阅。

把 webhook 用在续跑,而不是基础读取上

当 agent 需要在稍后某个事件发生后继续工作时,webhook 才最有意义。对简单只读流程,它通常不是必需的。

  • 在事件模型未证明前,早期集成仍以直接读取为主。
  • 当用户进展或系统变化需要定时跟进时,再用 webhook。
  • 优先使用显式的 continuation flow,而不是隐藏式后台逻辑。

每次投递都应配对一次 fresh read

事件 payload 更适合唤醒工作流;真正的用户动作判断,最好还是基于最新正式状态完成。

  • 让事件负责路由工作流,而不是取代数据层。
  • 在 runtime 代码和日志里显式保留幂等设计。
  • 保存足够元信息,方便排查重复或延迟投递。

Webhook 对比

只有当事件驱动明显优于直接轮询时,才值得进入。

模式最适合不适合
直接读取简单 request-response 流和第一版集成。工作流必须在未来外部事件后恢复。
轮询在事件模型尚未稳定时做短期过渡检查。流程开始变得浪费或对时机敏感。
Webhooks需要确定性唤醒行为的长时流程。你还没有明确事件归属和重新拉取计划。

决策矩阵

用这些规则判断什么时候该切到 webhook 设计。

情况

工作流可以在一次交互内完成

动作

继续使用直接读取。

原因

引入事件基础设施只会增加复杂度。

情况

工作流需要在稍后用户进展后继续

动作

创建 webhook 订阅,并在投递时重新拉取状态。

原因

这是恢复流程并保持数据新鲜度的最干净方式。

情况

出现重复或延迟投递

动作

让续跑保持幂等,并记录每次投递尝试。

原因

事件系统的可靠性来自重复安全,而不是来自绝不重复。

Webhook 生命周期示例

显式创建订阅,再通过 runtime tooling 列出或检查它们。

创建订阅
1curl -X POST "https://api.profileclaw.com/api/v1/webhooks" -H "Authorization: Bearer $PROFILECLAW_API_KEY" -H "Content-Type: application/json" -d '{"url":"https://example.com/profileclaw/webhooks","events":["profile.updated","assessment.completed"]}'
列出订阅
1curl "https://api.profileclaw.com/api/v1/webhooks" -H "Authorization: Bearer $PROFILECLAW_API_KEY"

下一步

事件模型清楚后,再去验证精确契约和失败分支。