使用 webhook 触发自动化 - DingTalk Help Center

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机器人支持的消息结构，你可以在「发送消息到该群组」的执行动作中，将「消息来源」切换为“源数据解析”，将这些参数自动解析为消息体发送出去。）

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
Body	JSON，需要包含触发关键字才能正常触发流程	{ “key”: “value” }

名称	类型	必填	描述
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 的示例代码如下（中括号表示需替换的变量，无需在实际代码中写入）：

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 接收正常时，响应体示例如下：

{
"msg": "",
"data": { },
"code": 0
}

当 webhook 出现报错时，响应体示例如下：

{
"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机器人支持的消息结构，那么你可以在「发送消息到该群组」的执行动作中，将「消息来源」切换为“源数据解析”，并选择webhook「接收到数据时」的节点出参作为源数据，即可将这些参数自动解析为消息体发送出去。

​1 功能简介

​2 使用场景

​3 使用方法

​3.1 设置触发关键词。

​3.2 设置参数格式

​3.2.1 选择参数格式为JSON时

​3.2.2 选择参数格式为Text时

​3.2.3 选择参数格式为None时

​3.3 配置webhook地址

​3.4 发送 Http 请求

​4 请求头（Header）及示例

​5 请求体

​6 响应体及示例

​7 错误码

​8 应用实践