> ## Documentation Index
> Fetch the complete documentation index at: https://help.dingtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.
# 使用 webhook 触发自动化
> 使用 Webhook 触发 AI 表格自动化：外部系统通过推送事件数据至专属 Webhook 地址来触发流程，支持关键词过滤和 JSON/Text/None 三种参数格式，适用于 ERP 同步、监控告警等场景。
## 1 功能简介
Webhook允许不同的系统之间相互传递数据与信息。**当你关注的系统有新事件发生时，你就会自动接收到数据**。Webhook地址就像是一个通讯地址，用于接收这些数据，确保你能及时获取信息。
* 注意：Webhook是一个面向开发者的高级功能，请在开发者的帮助下使用此功能。
> ⚠️请保管好webhook地址，不要公布在外部网站，一旦产生泄露，可能会引发大量的危害信息传入，耗尽组织的开发资源，为组织带来资源损失和安全风险。
## 2 使用场景
通过设置Webhook，你可以“订阅”某个系统或应用的更新，比如：
* 内部系统数据同步：在ERP、CRM等内部系统设置Webhook，可实现系统之间的数据同步，免去人工手动同步。
* 网站内容更新通知：在你关注的网站设置Webhook，有新内容时就会主动通知你，不需要你反复打开网站查看。
* 监控和报警通知：在监控系统或报警平台设置Webhook，可以实时监控系统的健康状况，帮助你尽快处理问题。
## 3 使用方法
### 3.1 设置触发关键词。
接收到的数据包含关键词时，才会触发流程。点击「添加关键词」可设置多个关键词（上限10个），接收到的数据包含任意1个关键词时，都会触发流程。
### 3.2 设置参数格式
当你接收到来自于你关注的系统的参数时，这些参数也将继续向下传给后续的步骤。因此，**参数格式决定了在后续步骤中，流程将如何解析和引用这些参数。**
#### 3.2.1 选择参数格式为JSON时
在后续步骤中会按照 JSON 规则对这些参数进行结构化解析。因此，你需要**手动填写一段参数示例，以便在后续的步骤中，引用这些结构化的数据。**
#### 3.2.2 选择参数格式为Text时
在后续的步骤中你能以text的格式整段引用这些参数。（ 特别的，如果这段参数符合[DingTalk机器人支持的消息结构](https://open.dingtalk.com/document/orgapp/custom-bot-send-message-type#66407430cd5xr "DingTalk机器人支持的消息结构")，你可以在「发送消息到该群组」的执行动作中，将「消息来源」切换为“源数据解析”，将这些参数自动解析为消息体发送出去。 ）
#### 3.2.3 选择参数格式为None时
在后续步骤中将无法引用这些参数。
Webhook 参数的详细说明
### 3.3 配置webhook地址
点击「复制」按钮，将webhook地址配置到你想要关注的系统中。（每个自动化流程都会自动生成一个单独的webhook地址，**请保管好webhook地址，一旦泄露，可能会引发大量的危害信息传入，耗尽组织的开发资源**。）
### 3.4 发送 Http 请求
发送请求后，触发自动化流程。
| 参数 | 值 | 示例 |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Method | POST | - |
| URL | 触发条件中的 Webhook 地址 | [https://connector.dingtalk.io/webhook/flow/xxxxx](https://connector.dingtalk.io/webhook/flow/xxxxx "https://connector.dingtalk.io/webhook/flow/xxxxx") |
| Body | JSON，需要包含触发关键字才能正常触发流程 | \{ "key": "value" } |
## 4 请求头（Header）及示例
| **名称** | **类型** | **必填** | **描述** |
| ------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Authorization | string | 否 | 凭证校验（Bearer token）需通过请求头（Header）的方式传给AI表格自动化，Header 格式（区分大小写）如下： --header 'Authorization: Bearer \\\[真实的 Bearer token]' 单引号在实际 Header 中必须输入。中括号\\\[]仅表示变量，在实际 Header 中无需输入。 此处 Header 的 Key（键）固定为 Authorization，Value（值）有固定前缀 Bearer。 请注意，Bearer 前缀和真实的 Bearer token 中间，必须加一个空格。 |
| Client-Token | string | 否 | 幂等的 Header 中，Key（键）固定为 Client-Token，Value（值）由用户生成，通常使用 uuid。 若此值为空，表示将发起一次新的请求。若此值非空，表示幂等的进行更新操作，相同的值 3 小时内只会触发一次。 |
Bearer token 的示例代码如下（中括号表示需替换的变量，无需在实际代码中写入）：
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --location --request POST '[真实 webhook 地址]' \
--header 'Authorization: Bearer [真实 Bearer token]' \
--header 'Content-Type: application/json' \
--data-raw '{[真实请求体内容]}'
```
## 5 请求体
按需设置即可，格式需符合 JSON 规范。
## 6 响应体及示例
响应体中的 code 非 0 时表示失败。
当 code 不是 0 时，你可以对照下文“相关报错”表格中的错误码和文案来排查问题。
当 webhook 接收正常时，响应体示例如下：
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"msg": "",
"data": { },
"code": 0
}
```
当 webhook 出现报错时，响应体示例如下：
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"data": { },
"code": 800004509,
"msg": "webhook trigger workflow is disabled"
}
```
## 7 错误码
若 webhook 触发出现报错，你需要在发出请求方查看报错情况，根据下表的错误码和报错文案来排查问题。
| **错误码** | **报错文案** | **报错原因** | **解决方法** |
| --------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| 800005649 | 未通过凭证校验 | 开启了凭证校验，但HTTP 请求中携带的凭证与自动化流程中所需的凭证不符，导致流程无法运行。 | 重新检查和输入凭证。 |
| 800005650 | IP 地址不在白名单中，请检查 | 开启了 IP 白名单，且发送请求的 IP 不在白名单内。 | 将对应 IP 加入白名单，或更换 IP 地址重新发送。 |
| 800005647 | 请求内容大小超出上限，请减少内容 | webhook 接收 HTTP 请求的大小超出了 4 MB。 | 请减少内容。 |
| 800005646 | 存在调用自身的 HTTP 节点，造成死循环，请修改 HTTP 节点请求地址 | 自动化流程的触发条件为“webhook 触发时”，执行操作为“发送 HTTP 请求”，且 HTTP 的请求 URL 和当前流程的 webhook 地址一致，导致流程进入了循环触发。 | 修改“发送 HTTP 请求”中的 URL，不可与 webhook 地址一致。 |
| 800005652 | 请求过于频繁，请稍后再试 | webhook 接收 HTTP 请求的频率超出了限制，被限流。 - 整个AI表格的 webhook 触发频率上限为 50 次/秒。 - 单个自动化流程的 webhook 触发频率上限为 5 次/秒。 - 针对不开启凭证校验（Bearer token）的自动化流程，每个流程的频率上限为 1 次/秒。 | 稍后再试。 |
| 800006003 | 请求体不符合 JSON 格式规范，请修改后重新请求 | 通常发生在使用“通过发送请求设置”的方法设置输出的时候，指接收到的请求体的 JSON 格式有误。 | 请重新检查请求体的 JSON，修改后重试。 |
## 8 应用实践
1、假如你是一家餐饮企业的管理员，**你想将内部的货品系统数据及时同步到DingTalk群聊内**，那么你可以在「参数示例」中**手动填入货品系统将要传给你的参数示例**（比如新品名称、规格、茶底、原料），在「发送消息到该群组」中你可以自定义消息内容，点击+号就能**引用这些参数，及时把新品的详情信息同步到群里。**
2、**假如你之前在群聊内使用过「自定义机器人」**，并且你所关注的系统传给你的参数符合[DingTalk机器人支持的消息结构](https://open.dingtalk.com/document/orgapp/custom-bot-send-message-type#66407430cd5xr "DingTalk机器人支持的消息结构")，那么你可以在「发送消息到该群组」的执行动作中，**将「消息来源」切换为“源数据解析”**，并选择webhook「接收到数据时」的节点出参作为源数据，即可将这些参数**自动解析为消息体发送出去。**
