Webhook 与事件订阅
在 TaoApex 账户中发生事件时接收实时通知。使用安全的 Webhook 端点无缝集成到您的系统中。
什么是 Webhook？
Webhook 允许您在 TaoApex 账户中发生特定事件时接收实时 HTTP 通知。无需轮询 API 获取更新，TaoApex 会在事件发生的瞬间将数据推送到您的端点。这使得与您的内部系统、数据库和工作流程的即时集成成为可能。
支持的事件类型
订阅对您的集成最重要的事件。每种事件类型都包含带有所有相关信息的结构化负载。
message.created创建新消息时触发
message.updated消息更新或编辑时触发
session.started新对话会话开始时触发
session.ended对话会话结束时触发
file.uploaded文件上传到对话时触发
user.subscribed用户订阅计划时触发
负载结构
每次 Webhook 传递都包含带有标准化字段的 JSON 负载。数据对象包含特定于事件的信息。
{
"id": "evt_xxxxxxxxxxxx",
"type": "message.created",
"timestamp": "2026-07-19T12:00:00Z",
"data": {
"message_id": "msg_xxxxxxxxxxxx",
"user_id": "usr_xxxxxxxxxxxx",
"content": "...",
"model": "claude-sonnet-4-20250514"
}
}安全性
TaoApex Webhook 以安全性为优先设计。所有 Webhook 通信都经过加密和验证。
HMAC 签名
每个 Webhook 在 X-TaoApex-Signature 头中包含 HMAC-SHA256 签名。验证此签名以确保请求来自 TaoApex。
TLS 加密
所有 Webhook 传递都使用 HTTPS/TLS 1.2+ 以确保数据在传输过程中加密。
传递与重试
TaoApex 保证所有 Webhook 事件至少传递一次。如果您的端点未能以 2xx 状态码响应，我们将使用指数退避进行重试。
常见问题
Webhook 端点的超时时间是多少？
您的 Webhook 端点必须在 30 秒内响应。如果处理时间较长，请立即用 200 状态确认收到，然后异步处理。
如何验证 Webhook 签名？
每个 Webhook 都包含一个 X-TaoApex-Signature 头。使用您的 Webhook 密钥计算原始请求体的 HMAC-SHA256，并与头值进行比较。
如果我的端点暂时不可用会怎样？
TaoApex 会自动使用指数退避重试失败的传递：1 分钟后、5 分钟后、30 分钟后、2 小时后和 12 小时后。5 次尝试失败后，事件被标记为失败。
我可以只接收特定事件的 Webhook 吗？
可以。配置 Webhook 端点时，您可以选择要订阅的事件类型。您将只收到这些事件的通知。
Webhook 传递有限制吗？
TaoApex 支持每个账户最多 100 个 Webhook，所有端点每分钟最多 1,000 次传递。如需企业级更高限制，请联系我们。