Webhook 推送
第三方 → Shulex：新消息触发接口
当第三方系统有新消息时，向 Shulex 在渠道配置页面展示的 Webhook 地址发起 POST 请求。
Webhook 地址
请在 Shulex 中创建 Custom Ticket 渠道后，直接复制页面展示的 Webhook 地址。不要手动拼接 Webhook URL。
路径字段
安全说明
{xToken} 与 {channelId} 均由 Shulex 生成并在渠道配置页面展示，接入方只需复制使用。- Webhook 使用
{xToken}/{channelId} 双参数定位渠道。
- 禁止只使用数字
channelId 作为 Webhook 凭证，避免被枚举调用。
- Shulex 会校验访问凭证与渠道是否属于同一账号。
- 请妥善保管完整 Webhook 地址，不要将其暴露在公开代码、日志或客户端中。
请求格式
请求体字段
Webhook 只作为处理触发器。请求体至少需要 ticketId；完整工单内容、消息历史和附件均由 Shulex 通过 queryUrl 拉取，不从 Webhook body 读取。
messageId 关联建议
建议每次新消息触发都提供稳定且唯一的 messageId。第三方接收回复或标签回调时，可使用 ticketId + messageId + callbackType 实现幂等；未传 messageId 时，回调不会包含空字段，以保持旧接入兼容。
响应格式
成功响应
code=200 仅表示 Shulex 已接收请求并进入处理链路，不表示回复或标签回调已经完成。
常见错误
接入建议
- Webhook 应在新消息到达后尽快发送，避免同一工单上下文过期。
- 第三方应尽快返回
queryUrl、replyUrl 和 tagsUrl 的响应，并对回调实施幂等处理。
- 完整字段定义请参阅 工单查询、AI 回复回调 和 标签回调。
