> ## Documentation Index
> Fetch the complete documentation index at: https://beaver.voc.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook 推送

> 第三方 → Shulex 的新消息触发接口

# Webhook 推送

> 第三方 → Shulex：新消息触发接口

当第三方系统有新消息时，向 Shulex 在渠道配置页面展示的 Webhook 地址发起 `POST` 请求。

## Webhook 地址

请在 Shulex 中创建 Custom Ticket 渠道后，直接复制页面展示的 Webhook 地址。**不要手动拼接 Webhook URL**。

```text theme={null}
POST https://<host>/api_v2/intelli/v2/webhook/CUSTOM_TICKET/{xToken}/{channelId}
```

### 路径字段

| 字段              | 说明                             |
| --------------- | ------------------------------ |
| `CUSTOM_TICKET` | 固定平台标识，必须全大写                   |
| `{xToken}`      | Shulex 生成的渠道访问凭证               |
| `{channelId}`   | Shulex 生成的 Custom Ticket 渠道 ID |

## 安全说明

* `{xToken}` 与 `{channelId}` 均由 Shulex 生成并在渠道配置页面展示，接入方只需复制使用。
* Webhook 使用 `{xToken}/{channelId}` 双参数定位渠道。
* 禁止只使用数字 `channelId` 作为 Webhook 凭证，避免被枚举调用。
* Shulex 会校验访问凭证与渠道是否属于同一账号。
* 请妥善保管完整 Webhook 地址，不要将其暴露在公开代码、日志或客户端中。

## 请求格式

```http theme={null}
POST {webhookUrl}
Content-Type: application/json

{
  "ticketId": "order-2024-88001",
  "messageId": "msg-20260716-001",
  "eventType": "message.created"
}
```

### 请求体字段

| 字段          | 类型     | 必填 | 说明                                       |
| ----------- | ------ | -- | ---------------------------------------- |
| `ticketId`  | string | 是  | 工单唯一 ID；Shulex 使用它调用 `queryUrl` 拉取完整工单详情 |
| `messageId` | string | 否  | 本次消息的唯一 ID；存在时会在回复和标签回调中原样返回             |
| `eventType` | string | 否  | 第三方事件类型，用于记录本次触发，例如 `message.created`    |

<Warning>
  Webhook 只作为处理触发器。请求体至少需要 `ticketId`；完整工单内容、消息历史和附件均由 Shulex 通过 `queryUrl` 拉取，不从 Webhook body 读取。
</Warning>

### messageId 关联建议

建议每次新消息触发都提供稳定且唯一的 `messageId`。第三方接收回复或标签回调时，可使用 `ticketId + messageId + callbackType` 实现幂等；未传 `messageId` 时，回调不会包含空字段，以保持旧接入兼容。

## 响应格式

### 成功响应

```json theme={null}
{
  "code": 200,
  "message": "ok"
}
```

<Note>
  `code=200` 仅表示 Shulex 已接收请求并进入处理链路，**不表示**回复或标签回调已经完成。
</Note>

### 常见错误

```json theme={null}
{
  "code": 401,
  "message": "invalid token"
}
```

```json theme={null}
{
  "code": 400,
  "message": "unsupported platform: CUSTOM_TICKET"
}
```

```json theme={null}
{
  "code": 422,
  "message": "platform not configured"
}
```

| code  | 说明                                    |
| ----- | ------------------------------------- |
| `200` | 已接收，进入处理链路                            |
| `400` | 平台标识不支持                               |
| `401` | 访问凭证无效或与渠道不匹配                         |
| `422` | 渠道未完成配置                               |
| `500` | 服务端处理异常，可保留 `ticketId` 联系 Shulex 支持排查 |

## 接入建议

* Webhook 应在新消息到达后尽快发送，避免同一工单上下文过期。
* 第三方应尽快返回 `queryUrl`、`replyUrl` 和 `tagsUrl` 的响应，并对回调实施幂等处理。
* 完整字段定义请参阅 [工单查询](/api/ticket-ai/third-party-api/query)、[AI 回复回调](/api/ticket-ai/third-party-api/reply) 和 [标签回调](/api/ticket-ai/third-party-api/tags)。