type 和 id,而非完整对象。当您收到 Webhook 事件时,需要通过 GET 调用直接获取该对象。这样可以避免在重试时传递过时数据,并使每次传递的数据量保持较小。
支持的事件类型
- 会话事件
- 密钥库事件
- 智能体事件
- 部署事件
- 部署运行事件
- 环境事件
- 记忆存储事件
注册端点
访问 OMA 控制台中的 Manage > Webhooks。 Webhook 端点由以下部分组成:- URL: 必须是端口 443 上的 HTTPS,且主机名可公开解析。
- 事件类型: 此端点接收的
data.type值列表。端点仅接收其已订阅的事件。 - 签名密钥: 创建时生成的 32 字节、以
whsec_为前缀的密钥。该密钥仅显示一次,因此请安全存储以用于验证 Webhook 传递。
验证签名
每次传递都携带webhook-id、webhook-timestamp 和 webhook-signature 标头。使用 SDK 的 unwrap() 辅助方法可一步完成签名验证和事件解析。如果签名无效或负载已超过 5 分钟,该方法会抛出异常。
将 ANTHROPIC_WEBHOOK_SIGNING_KEY 设置为端点创建时显示的以 whsec_ 为前缀的密钥。
处理事件
解析请求体,根据data.type 进行分支处理,并按 ID 获取资源。返回任何 2xx 状态码以确认接收。任何其他响应都会计入该端点的失败记录:3xx 会立即禁用端点(永远不会跟随重定向),而其他失败会被重试;有关重试和自动禁用规则,请参阅传递行为。
每个事件负载都具有相同的结构,包括事件类型、标识符以及事件发生时的时间戳。
event.id 对每个事件是唯一的,而非对每次传递唯一。如果您两次收到相同的 event.id,则表示这是一次重试,您可以将其丢弃。
传递行为
-
重复: 端点可能多次收到同一事件,且每次尝试传递的顶层
event.id都相同(与webhook-id标头的值相同)。请基于该值进行去重。 - 订阅范围: 事件仅传递给在其发出时刻已订阅该类型的端点。如果事件发出时没有任何端点订阅其类型,则该事件永远不会被传递,且之后订阅也不会回填该事件,因此请在需要某个事件类型之前就订阅它。
-
不保证顺序。 事件不会按其发生的顺序传递:即使结果先产生,
session.status_idled也可能在session.outcome_evaluation_ended之前到达;同一资源的.deleted事件也可能在.archived事件之前到达。请根据您获取的资源来驱动状态,而不是根据事件到达的顺序。 -
重试: 对于每个端点和事件,OMA 最多进行三次传递尝试(触发自动禁用的响应永远不会被重试,详见本节后文),重试之间采用带抖动的指数退避,间隔在 5 到 120 秒之间。每次尝试传递的
event.id都相同。最后一次尝试失败后,该事件会被丢弃:它不会排队等待后续传递,也没有任何信号表明它已丢失。Webhook 不是持久化日志,因此如果您需要观察每一次状态转换,请通过 API 列出或获取资源来进行核对。 -
时间戳:
webhook-timestamp标头在对传递尝试进行签名时打上时间戳,并在每次重试时重新生成,因此重试不会被 SDK 的新鲜度检查拒绝。它是传递尝试的时钟,而非事件的时钟:请使用事件负载中的created_at来获取事件发生的时间。 -
自动禁用: 在以下三种情况下,端点会被自动设置为
disabled,并附带机器可读的disabled_reason:- 端点返回
3xx响应。永远不会跟随重定向;这会在第一次尝试时立即禁用端点,原因为auto-disabled: endpoint URL returned a redirect (3xx)。如果您的端点已迁移,请在 OMA 控制台 中更新 URL 并重新启用该端点。 - 当 OMA 连接时,端点的 URL 解析为非公共 IP 地址。这会立即禁用端点,原因为
auto-disabled: endpoint URL resolved to an invalid address。 - 向该端点的传递持续失败了一段时间,原因为
auto-disabled after sustained delivery failures。触发条件是端点连续失败的时长,而非传递次数。单个2xx响应即可重置该时间窗口,因此单个不稳定的事件不会导致端点被禁用。
- 端点返回