配置客户 Webhook
为受支持的事件注册 HTTPS 接收端，保护签名密钥，并通过投递历史排查故障。
- 准备接收端使用可接收 JSON 的公网 HTTPS 端点。
- 订阅事件填写端点名称、URL 和事件类型。
- 保护签名保存一次性密钥并验证收到的请求。
- 检查投递根据状态和响应信息排查问题。
- 维护端点轮换密钥或撤销不再需要的目标地址。
受支持的客户事件
客户表单提供任务完成、发票开具和额度阈值事件。只选择接收端能够处理的事件。端点归属于个人或当前所选组织上下文。组织所有者和管理员可以管理端点；成员可以查看但不能更改。Webhook 仅发送通知，本身不能更改订单或发票。
- 在目标组织上下文中打开 Webhooks。
- 至少选择一个接收端能够处理的事件。
- 为不同环境使用不同端点。
注册公网目标地址
创建端点时需填写 2–120 个字符的名称、有效 URL 和一个或多个列出的事件。必须使用 HTTPS 和公网主机名。系统会拒绝本地、内部和私有 IP 目标，因此本地开发 URL 无法使用。确认接收端可接收 JSON 并返回成功 HTTP 响应后再提交。
- 在稳定的公网 HTTPS 地址部署接收端。
- 填写 URL、清晰的名称和事件选项。
- 提交一次，并修正页面指出的校验错误。
验证签名消息
创建时签名密钥只显示一次。请求包含事件、投递、时间戳和 HMAC 签名标头，以及包含事件 ID、类型、创建时间和数据的 JSON。请使用时间戳和未经修改的原始请求正文校验签名，限制合理的时间戳窗口，并以幂等方式处理重复 ID。不要在日志或支持消息中泄露密钥。
- 将密钥保存在接收端的受保护配置中。
- 使用未经修改的请求正文验证签名。
- 记录事件 ID，避免重复执行业务操作。
查看投递历史
页面显示所有端点最近 50 次投递。成功的 HTTP 响应会标记为成功。服务器错误和速率限制可能会触发重试；其他失败响应可能立即失败，且尝试次数不会超过重试上限。历史记录包含响应状态以及有限长度的响应正文或错误信息。如果事件未发生或端点未订阅该事件，记录中可能不会出现该事件。
- 检查事件、尝试次数、状态和最近错误。
- 修复接收端可用性、响应或速率限制问题。
- 查看后续投递是否成功。
轮换签名密钥
轮换会替换端点密钥并重新启用该端点。只使用旧值的接收端将无法验证新请求。请先准备接收端配置更新，再从目标端点行执行轮换，保存新值并尽快部署。如果密钥已泄露，请立即轮换并检查投递历史中是否存在异常活动。
- 确认接收端实例，并准备安全部署。
- 轮换目标端点并保存一次性密钥。
- 确认之后的一次预期投递成功。
替换或撤销端点
客户端控制项支持创建、轮换和撤销，但不支持直接修改 URL 或事件选择。若要更改这些设置，请创建替代端点，确认它能接收正确事件后，再撤销旧端点。撤销会停止后续投递并将其标记为非活动状态。退役目标地址或密钥泄露时应执行撤销，并在操作后检查列表。
- 使用更正后的 URL 或事件集合创建替代端点。
- 确认替代端点的投递成功。
- 撤销旧端点并确认其已停用。
常见问题
提供哪些事件？
任务完成、发票开具和额度阈值。
可以使用普通 HTTP 吗？
不可以。必须使用公网 HTTPS URL。
之后还能再次查看密钥吗？
不能。请轮换端点以生成新密钥。
为什么投递仍处于待处理状态？
临时服务器错误或速率限制可能导致重试。
为什么投递失败？
请查看响应和重试历史以了解原因。
可以编辑端点吗？
不可以。请创建并验证替代端点，再撤销旧端点。