> For the complete documentation index, see [llms.txt](https://doc.duaer.com/zh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.duaer.com/zh/portal/assistants/webhook.md).

# 助手 Webhook：让外部系统触发助手

所有者或管理员为助手创建一个 Webhook 地址；外部系统向它发 POST 请求，助手就为每位使用者运行一次，可以带一段文字作为数据。
## 创建 Webhook

1. 所有者或管理员打开 Duaer 设置 › 组织 ›「Duaer 员工端」›「员工助手」，在助手旁点「创建 Webhook」。
2. 复制显示出来的地址。它只显示这一次；Duaer 只保存它的哈希，之后找不回来。
3. 丢了或泄露了，再点一次「创建 Webhook」会换一个新地址，旧的立即失效。点「撤销 Webhook」则不再接受调用。

员工在自己的助手里只能看到「外部系统也可通过 Webhook 触发（由管理员管理）」，看不到地址。

## 请求

- 方法：POST，地址就是复制的那个，形如 https://<Duaer 地址>/rest/agent-hooks/<令牌>。地址本身就是凭据，不需要登录或其他请求头。
- 请求体（可选）：JSON。有字符串字段 text 时，传它；否则把整个 JSON 当作文字传。最多 4,000 个字符，多出的截掉。
- 传进去的内容只作为数据交给助手，不会被当成指令执行。

```
curl -X POST "https://<your Duaer address>/rest/agent-hooks/<token>" \
  -H "Content-Type: application/json" \
  -d '{"text": "Order 42 was cancelled by the customer"}'
```

## 响应

- 202：已接受。助手在后台为建它的人和每位被分享的同事各运行一次，结果写到各自的首页，并按设置发到聊天工具。
- 404：令牌不对，或者助手已停用、Webhook 已撤销。
- 429：这个助手今天的触发次数（每天 UTC 最多 24 次，和资料变化触发合计）用完了，或者同一个 IP 一分钟内超过 60 次。

响应不会返回助手的回答；回答只给能看到它的人。

## 安全

- 只有所有者和管理员能创建和撤销 Webhook，两者都记进审计日志。
- 运行时用每位使用者自己的权限读资料，外部系统看不到任何内容。
- 助手只读资料，不会因为 Webhook 执行操作。
- 更多见 [Duaer 怎么保护你公司的数据](/zh/security.md)。
## Questions

### Webhook 能拿到助手的回答吗？

不能。响应只说是否接受；回答写到使用者的首页，并按设置发到聊天工具。

### 地址泄露了怎么办？

在员工助手里再点一次「创建 Webhook」换新地址，或点「撤销 Webhook」，旧地址立即失效。

### 员工能自己创建 Webhook 吗？

不能，只有所有者和管理员能创建。

## 相关

- [让助手自己运行：定时、资料变化和 Webhook](https://doc.duaer.com/zh/portal/assistants/runs.md)
- [员工助手：在 Duaer 员工端建自己的助手](https://doc.duaer.com/zh/portal/assistants.md)
- [Duaer 怎么保护你公司的数据](https://doc.duaer.com/zh/security.md)