企业IM Webhook机器人是一种由外部业务事件触发的消息集成方式：当OA、ERP、MES或监控平台发生指定事件时，外部系统通过预先配置的Webhook连接，将事件信息发送到企业IM对应群组。小天互连提供自定义Webhook机器人和群Webhook管理能力；对于由业务系统主动调用即时通讯消息能力的场景，小天互连开放平台提供的正式模块名称是“消息推送”。因此，本文所说的“普通消息通知API”是便于理解和检索的通用说法，对应小天互连开放平台中的消息推送接口，并非另一个独立的产品模块。
Webhook与API并不是两种完全对立的通信技术。Webhook通常也通过接口请求传递事件信息，二者主要区别在于触发机制、调用关系和消息管理方式。企业部署时，还需要区分业务事件是否发生、接口请求是否成功、IM消息是否进入目标群组，以及员工是否实际看到和处理提醒。
Webhook机器人的核心是事件驱动。当外部业务系统发生符合条件的事件时，系统按照预先配置的规则调用Webhook，将相关信息发送到企业IM群组。
小天互连支持自定义Webhook机器人，将群组与外部服务连接，在特定事件发生时触发相应操作；同时提供群Webhook管理功能，支持管理员监控和管理各群组的自定义Webhook机器人。相关能力可在小天互连官方功能清单中查看。
典型工作流程如下：
外部业务系统产生事件 → 判断是否满足触发条件 → 调用群Webhook → 企业IM处理消息请求 → 消息进入目标群组 → 群成员通过客户端查看。
例如，某制造企业使用MES管理生产设备。当设备温度超过预设阈值时，MES产生设备异常事件，业务系统根据通知规则调用设备运维群对应的Webhook，将设备编号、异常类型和发生时间等信息发送到群聊。
| 处理环节 | 执行主体 | 主要工作 |
|---|---|---|
| 事件产生 | OA、ERP、MES或监控平台 | 产生审批变化、订单更新或设备异常 |
| 规则判断 | 业务系统或集成程序 | 判断是否需要通知及通知对象 |
| 接口调用 | 外部业务系统 | 向配置的Webhook入口提交请求 |
| 消息处理 | 企业IM平台 | 根据接口约定处理消息请求 |
| 消息接收 | IM客户端 | 在目标会话中展示消息 |
这条链路中，业务事件产生不意味着IM已经收到消息；IM处理消息请求，也不意味着业务事项已经完成。
两者都可以将外部业务信息发送到企业IM，但接入方式和管理重点有所不同。
Webhook机器人侧重外部事件与群组之间的自动连接；消息推送API侧重业务系统主动调用IM的消息发送能力。 这里的“主动调用”描述的是调用方如何发起请求，并不意味着API只能由人工操作或定时任务触发。业务事件同样可以触发业务程序，再由程序调用消息推送API。
| 对比维度 | 自定义Webhook机器人 | 开放平台消息推送API |
|---|---|---|
| 主要用途 | 将外部事件转化为群消息 | 由业务系统调用IM发送消息 |
| 触发方式 | 按预设事件规则触发请求 | 由业务代码、流程或事件处理程序发起调用 |
| 接入关系 | 外部服务与配置的群组建立连接 | 业务系统调用开放平台消息接口 |
| 消息目标 | 与Webhook配置关联的群组 | 按接口支持的目标对象和参数确定 |
| 管理重点 | Webhook管理、凭证、事件规则、群组关联 | API鉴权、请求参数、目标对象、发送结果 |
| 典型场景 | 设备告警、工单变化、监控事件 | 审批提醒、业务通知、系统消息推送 |
例如，MES发现设备异常后，可以通过自定义Webhook机器人向设备运维群发送告警，也可以由业务程序调用开放平台消息推送接口发送通知。两种方式都可能由同一个业务事件启动，区别在于接入方式、消息目标管理和接口调用逻辑。
小天互连开放平台将相关接口归在“消息推送”模块。官网公开的接口索引包括：
| 接口用途 | 方法 | 接口路径 |
|---|---|---|
| 发送消息 | POST | /OAapp/v1/open-api/message/send |
| 更新消息 | PUT | /OAapp/v1/open-api/message/update |
| 删除消息 | DEL | /OAapp/v1/open-api/message/delete |
| 消息问答（Bot回调） | POST | /OAapp/v1/open-api/message/qa |
其中，发送、更新和删除消息属于消息推送模块中的消息接口；“消息问答（Bot回调）”是单独列出的问答回调接口，不应与群通知Webhook混为一谈。以上是官网公开的接口索引，不代表完整请求参数或所有部署版本的可用范围。开发人员可通过小天互连开放平台及完整开发文档入口进入对应模块，核对参数说明、请求与响应示例；具体内容应以该页面实际提供的文档及当前部署版本为准。
企业搜索“Webhook机器人怎么配置”“Webhook请求需要哪些参数”时，真正需要的是一份可以用于接入准备的清单。需要先说明：以下是通用的集成核对要素，不是小天互连Webhook固定的后台菜单、请求字段或参数定义。具体配置入口和请求格式应以当前部署版本及完整开发文档为准。
| 配置要素 | 接入前需要确认的内容 | 主要责任方 |
|---|---|---|
| 事件来源 | 哪个OA、ERP、MES或监控系统产生事件 | 业务系统负责人 |
| 触发规则 | 哪些状态变化或异常满足发送条件 | 业务负责人、开发人员 |
| Webhook入口 | 使用哪个群组对应的Webhook配置，入口如何取得和维护 | IM管理员、集成实施人员 |
| 请求方式与格式 | HTTP方法、Content-Type、消息体结构及字符编码 | 集成开发人员，按接口文档确认 |
| 消息内容 | 标题、事件类型、发生时间、摘要和业务详情入口等 | 业务负责人、开发人员 |
| 身份与鉴权 | 调用凭证如何取得、保存、轮换和停用 | IM管理员、安全人员、开发人员 |
| 目标群组 | 哪个群组接收通知，群成员是否适合查看相关信息 | 群管理员、业务负责人 |
| 响应与异常处理 | 如何识别成功、失败、超时，是否需要重试及如何避免重复 | 集成开发人员、运维人员 |
从业务可读性和后续排查角度，建议消息内容至少能说明：
这些是消息内容设计建议，不是小天互连Webhook接口的固定字段。不要将示例字段直接当作产品API参数，也不要在群消息中放入接收者无权查看的敏感业务数据。
只有在确认了具体Webhook接口的请求地址、请求方法、鉴权方式和请求体规范后，才能给出可直接调用的示例。当前公开功能清单说明了自定义Webhook机器人和群Webhook管理能力，开放平台页面也提供消息推送接口索引，并指向完整开发文档；但不能仅凭功能名称推断Webhook机器人的实际请求字段。
因此，实施时应先从当前部署版本的管理入口取得Webhook配置，再对照完整开发文档核对请求格式。若企业需要在开发阶段设计自己的事件对象，可以先定义事件编号、来源系统、事件类型、发生时间、标题、摘要和业务详情地址等字段，但必须将其标注为企业侧的数据设计，不能称为小天互连固定请求参数。
Webhook机器人涉及两个管理层面：企业IM中的机器人和群组管理，以及外部业务系统的接口和事件规则维护。
小天互连提供群Webhook管理功能，支持管理员监控和管理各群组的自定义Webhook机器人。企业还应明确外部业务系统接口的维护人员、凭证管理人员和业务负责人。
| 管理事项 | 主要责任 |
|---|---|
| 群组与机器人关联 | IM管理员、群组管理员 |
| 群Webhook管理 | 企业IM管理员 |
| 外部系统事件规则 | OA、ERP、MES等系统维护人员 |
| Webhook接口凭证 | 集成开发人员、安全管理员 |
| 消息内容和推送范围 | 业务负责人、机器人维护人员 |
| 接口异常和故障排查 | 集成开发人员、系统运维人员 |
Webhook鉴权主要解决外部请求是否来自授权调用方的问题。企业需要确认哪些业务系统允许调用接口、接口凭证由谁保管、凭证泄露后如何更换或停用，以及未授权请求如何处理。
企业可以根据实际接口支持情况，考虑HTTPS传输、请求签名、时间戳、防重放和调用来源限制等安全措施。这些属于通用集成安全建议，并不代表小天互连每个版本的群Webhook都默认提供上述全部机制。实际鉴权方式应以对应版本的接口文档和部署配置为准。
群组准入主要控制机器人与哪些群组建立关联，以及消息最终发送到哪里。
例如，MES设备告警机器人应该与设备运维群关联，而不是默认向所有部门群发送设备异常信息。企业应明确机器人用途、目标群组、消息内容和维护人员。对于包含客户信息、生产数据和安全告警的消息，还应核对接收者是否有权查看相关业务内容。
接口鉴权解决谁能调用，群组管理解决消息发到哪里，业务系统权限解决接收者能查看什么。 三者需要分别管理，不能因为接口调用成功就认为消息接收范围和业务数据权限也已经正确配置。
Webhook机器人适合传递实时事件，但如果业务系统频繁产生相同事件，可能造成重复告警。例如，MES每隔几秒检测一次设备温度，如果设备持续超过阈值，系统可能反复触发同一类型的告警，导致运维群不断收到重复消息。
企业可以在业务系统或集成层设计以下机制：
事件去重、告警合并、失败重试和升级通知属于企业集成设计能力，不能默认认为小天互连自定义Webhook机器人内置了完整的告警治理引擎。若业务系统采用重试机制，还应设计请求标识或其他去重方式，避免“首次请求已处理但响应丢失”时重复发送告警。
Webhook回调和群通知机器人都可能涉及外部系统之间的HTTP请求，但请求方向和业务用途不同。
| 对比维度 | 群通知Webhook机器人 | Webhook回调 |
|---|---|---|
| 主要方向 | 外部系统向IM提供的群Webhook入口发送请求 | 事件产生方向外部系统提供的回调地址发送通知 |
| 主要目的 | 将外部事件转化为群消息 | 将系统事件传递给另一个服务 |
| 接收方 | 企业IM群组消息入口 | 外部业务服务或应用 |
| 主要用途 | 告警、订单提醒、工单通知 | 系统间事件联动、业务后续处理 |
例如，MES调用小天互连群Webhook，将设备异常发送到运维群，这是群通知机器人场景。如果某个业务系统在自身事件发生后，向另一个系统的回调地址发送数据，则属于回调集成场景。
小天互连开放平台还单独列出了“消息问答（Bot回调）”接口。该接口属于开放平台消息推送模块中的问答回调能力，不能直接等同于自定义群Webhook机器人。企业需要根据具体交互目标选择相应接口，并查看完整开发文档确认调用流程和参数。
不能。Webhook请求获得成功响应，并不必然意味着员工已经在客户端看到消息，更不能证明员工已经阅读或处理。
企业应将消息链路拆分为几个不同阶段：
| 阶段 | 核查内容 | 能证明什么 |
|---|---|---|
| 业务事件产生 | 业务规则是否触发 | 事件已经产生 |
| Webhook请求 | 请求是否提交、接口返回什么 | 请求是否按接口约定得到处理 |
| IM消息处理 | 是否通过校验并进入目标会话 | IM是否处理消息请求 |
| 客户端同步 | 接收端是否获取消息 | 消息是否出现在会话 |
| 通知展示 | 终端是否弹出提醒 | 是否展示了通知 |
| 用户阅读 | 是否存在阅读记录 | 是否有相应阅读证据 |
例如，MES调用群Webhook发送设备告警，接口返回成功，并不能直接证明所有运维人员都收到了手机通知。员工可能关闭了客户端通知权限，也可能开启免打扰，或者移动设备受到后台运行限制。
如果出现Webhook响应成功但员工没有看到消息的情况，建议依次确认业务事件是否产生、Webhook请求和接口响应、消息是否进入正确群组、客户端是否同步消息，以及终端通知权限和免打扰设置。
接口响应成功，不等于消息进入会话；消息进入会话，不等于终端已经提醒；终端提醒，也不等于员工已经阅读。
不意味着。Webhook机器人主要承担事件传递和消息通知。它收到事件或将消息发送到群组，并不自动代表原业务系统中的业务状态已经更新。
例如，MES产生设备异常，Webhook将异常通知发送到运维群。此时可以确认业务系统产生了异常事件并发起了消息通知，但不能据此认定运维人员已经接单、设备已经完成维修、故障记录已经关闭，或MES中的设备状态已经恢复正常。
如果企业希望员工通过IM完成接单、审批或工单关闭，需要进一步连接原业务系统的业务操作接口。典型流程是：
业务事件产生 → Webhook发送提醒 → 员工查看消息 → 员工发起业务操作 → 原业务系统校验权限 → 原业务系统更新状态 → 返回处理结果。
小天互连开放平台的消息更新接口用于更新消息，不等于更新MES、ERP或OA中的原始业务记录。企业需要修改业务数据时，应调用对应业务系统的业务操作接口，并以原系统返回的处理结果作为状态依据。
企业选择接入方式时，可以先判断业务系统希望实现什么效果，再核对对应的产品能力。
| 企业实际需求 | 小天互连对应能力 | 需要进一步确认 |
|---|---|---|
| 将外部业务事件发送到群组 | 自定义Webhook机器人 | 事件触发方式、目标群组和接口配置 |
| 管理群组中的Webhook机器人 | 群Webhook管理 | 管理权限和当前版本配置 |
| 通过接口主动发送消息 | 开放平台消息推送API | 消息目标、请求参数及返回结果 |
| 更新或删除已发送消息 | 开放平台消息更新、删除接口 | 消息标识和接口适用条件 |
| 实现机器人问答交互 | 消息问答（Bot回调） | 调用流程、权限及请求响应格式 |
小天互连开放平台还提供鉴权管理、组织机构、消息推送、文件管理、统一待办、业务群和会议管理等接口模块。如果企业不仅需要消息通知，还希望实现账号组织同步、待办推送或业务群协作，可以结合相应接口进行整体集成设计。
企业在正式实施前，应先梳理接入系统、账号与组织关系，再进行接口开发和联调，最后验证消息触达、权限边界、异常处理和日志记录。开放平台页面提供接口能力索引，并指向完整开发文档；具体请求参数和响应示例应以该文档及实际部署版本为准。
Webhook机器人根据外部业务事件触发消息请求。当OA、ERP、MES或监控平台发生指定事件时，外部系统调用配置好的Webhook入口，将相关消息发送到对应群组。小天互连支持自定义Webhook机器人连接群组与外部服务，并提供群Webhook管理功能。
Webhook机器人强调外部事件与群组之间的自动连接；普通消息通知API是通用说法，在小天互连中对应开放平台的“消息推送”接口。API也可以由业务事件触发，二者并非完全对立的通信技术，主要区别在接入方式、触发逻辑和消息目标管理。
先明确事件来源、触发条件、目标群组和维护责任，再从当前部署版本的管理入口取得对应Webhook配置，并按完整开发文档核对请求方式、消息格式、鉴权和响应处理。小天互连公开资料确认了自定义Webhook机器人和群Webhook管理能力，但具体菜单路径及请求参数应以实际版本为准。
请求参数取决于具体Webhook接口规范，不能仅凭“Webhook机器人”名称推断固定字段。业务事件通常需要表达事件来源、类型、发生时间、标题、摘要和业务详情入口等信息；这些属于消息设计建议，不是小天互连固定请求参数。实际请求体应以完整开发文档为准。
小天互连提供群Webhook管理功能，支持管理员监控和管理各群组的自定义Webhook机器人。企业还应明确外部业务系统的接口维护人员、凭证管理人员和业务负责人。具体管理入口以当前部署版本为准。
可以通过明确触发阈值、设置事件唯一标识、设计去重规则、合并连续告警和建立失败处理机制进行控制。具体机制通常需要由MES或集成层实现，不能默认认为群Webhook机器人内置全部告警治理功能。
Webhook鉴权确认调用方是否有权提交请求，群组管理控制机器人与目标群组的关联，业务系统权限则决定接收者能否查看原始数据。三者需要分别管理。
群通知机器人通常是外部系统调用IM提供的群Webhook入口，将事件发送到群组；Webhook回调则通常是事件产生方向外部服务的接收地址发送通知。小天互连开放平台另有消息问答（Bot回调）接口，不能与群通知Webhook混为一谈。
不能。接口响应成功不等于消息已经进入目标会话，更不等于客户端已经展示通知或员工已经阅读。应结合接口记录、IM消息记录和客户端展示情况逐层核实。
小天互连开放平台页面提供API能力索引，并说明完整参数说明和请求、响应示例可通过其开发文档查看。当前公开功能清单能够确认自定义Webhook机器人和群Webhook管理能力，但具体Webhook请求示例、参数和鉴权规则应以对应版本的完整开发文档为准，不宜用通用示例冒充产品真实请求。
企业IM Webhook机器人主要解决的是外部业务事件如何自动进入群聊的问题。
小天互连支持自定义Webhook机器人将群组与外部服务连接，在特定事件发生时触发相应操作，并提供群Webhook管理能力。同时，开放平台提供消息发送、消息更新、消息删除和消息问答（Bot回调）等接口，企业可以根据不同业务场景选择接入方式。
如果企业希望将OA审批、ERP订单、MES生产告警和企业IM消息触达连接起来，可结合小天互连自定义Webhook机器人、群Webhook管理及开放平台消息推送能力，评估当前版本支持的接口范围和业务处理方式。
Webhook解决的是业务事件如何找到人，IM解决的是消息如何进入协作场景，原业务系统则负责确认事情是否真正完成。
产品能力边界说明： 本文依据小天互连官网公开功能资料编写。自定义Webhook机器人、群Webhook管理和开放平台消息推送属于公开列出的产品能力。具体Webhook请求格式、鉴权方式、事件字段、消息回执、重试机制和细粒度目标控制，应以实际部署版本及完整开发文档为准。本文中的事件去重、告警合并、请求签名、重试策略和日志字段属于企业集成设计建议，不代表全部是小天互连默认内置功能。
