美洽Webhooks怎么用？对话客户和工单数据自动同步方法

美洽 Webhooks 用来把对话、客户和工单变化自动同步到自己的 CRM 或业务系统。先配置接收数据的 Webhook URL，再选择需要监听的事件，例如新对话、客户更新、工单处理或结束。服务器收到数据后先校验签名，再按事件类型保存或更新对应记录。核心就四步：配置回调地址，选择事件，校验签名，同步数据。

美洽Webhooks在哪里配置

Webhooks 配置重点就是添加回调地址、选择监听事件，再把 Secret 交给开发人员做签名校验。

先配置Webhook接收地址

• 进入Webhooks设置： 在美洽后台找到开发者相关的 Webhooks 设置，添加自己的服务器回调 URL。

• 选择监听事件： 根据业务选择对话创建、客户更新、工单状态变化等事件，不需要把所有事件全部开启。

• 保存Secret： 配置后保存对应密钥，后续服务器要用它校验 Meiqia-Signature，确认请求确实来自美洽。

再测试Webhook是否正常

• 触发测试事件： 新建一条对话、修改客户资料或更新工单，确认服务器能收到对应 POST 请求。

• 返回成功状态： 接收成功后服务器应正常返回 200，表示本次推送已经处理。

• 记录请求ID： 保存每次 Webhook 的唯一请求标识，写入数据前先去重，避免同一事件重复处理。

美洽对话事件怎么自动同步

对话自动同步的重点是监听创建、更新、分配和结束事件。事件触发后，美洽会把对应对话数据推送到配置好的 Webhook 地址。

先选择需要监听的对话事件

• 创建对话： 监听 conversation.created，新客户产生对话后就能把数据同步到自己的 CRM 或业务系统。

• 更新对话： 监听 conversation.updated，对话信息发生对应更新时，可以继续同步最新数据。

• 结束和分配： 需要跟踪完整流程时，再监听 conversation.closed 和 conversation.scheduled，记录对话结束及首次分配客服。

再处理收到的对话数据

• 按事件类型处理： 服务器收到请求后先读取 event，再根据事件类型新增或更新对应对话记录。

• 按请求ID去重： Webhook 请求包含唯一 id，保存前先检查是否已经处理，避免重复写入。

• 成功后返回200： 数据处理成功后及时返回 HTTP 200。美洽官方目前说明 Webhook 推送失败暂无重试机制，因此接收端要做好日志和异常补偿。

美洽客户资料更新怎么监听

客户资料同步主要监听创建、更新和删除事件。客户信息变化后，美洽会把对应数据推送到你的 Webhook 地址。

先选择客户事件

• 创建客户： 监听 client.created，新客户创建或访客转成顾客时，可以自动同步到自己的 CRM。

• 更新客户： 监听 client.updated，客服在工作台修改客户资料后，可以同步最新信息。

• 删除客户： 监听 client.deleted，客户被删除后，自己的系统也可以同步更新对应状态。

再处理客户数据变化

• 按客户ID匹配： 收到事件后先找到对应客户，再更新原记录，避免重复创建。

• 只更新变化内容： 姓名、电话、微信、邮箱、备注等字段变化时，按实际业务同步即可。

• 做好去重记录： 保存 Webhook 请求唯一 ID，同一个事件已经处理过就不要重复写入。

美洽工单状态变化怎么自动推送

工单状态变化可以通过 Webhooks 自动推送。重点监听处理中、已结束和工单回复这些事件，再同步到自己的系统。

先选择需要监听的工单事件

• 首次处理中： 监听 new_ticket.processing_first，工单第一次进入处理中状态时，就能自动收到通知。

• 每次处理中： 监听 new_ticket.processing_every，工单每次重新进入处理中状态都可以继续同步。

• 结束和回复： 监听 new_ticket.closed 和 new_ticket.comment，分别同步工单结束和新增回复。

再同步到自己的业务系统

• 按工单ID更新： 收到事件后，根据 businessId 找到对应工单，再更新状态和处理记录。

• 保存回复内容： 工单回复事件会带上回复内容、回复人和回复时间，可以同步到 CRM 或内部系统。

• 按业务触发后续动作： 工单变成处理中或结束后，可以由自己的系统继续发送内部提醒或客户通知，不需要人工反复同步状态。

美洽Webhook签名校验和异常重试怎么处理

Webhook 接收后先校验签名，再处理业务数据。美洽官方说明，推送失败目前暂无自动重试机制，所以企业自己的系统要做好日志和补偿。

先做好Webhook签名校验

• 读取请求Body： 服务器收到 Webhook 后，先读取完整请求 Body，不要修改原始内容。

• 校验Meiqia-Signature： 按官方规则把 Body 和 Secret 拼接后进行 SHA1 计算，再和请求头里的 Meiqia-Signature 对比。

• 校验通过再处理： 签名不一致的请求不要直接写入 CRM、工单或客户系统，避免异常数据进入业务库。

再做好失败补偿和去重

• 成功及时返回200： 数据处理成功后返回 HTTP 200，让本次 Webhook 推送正常结束。

• 不要依赖自动重试： 美洽官方当前说明 Webhook 推送失败暂无重试机制，因此接收失败时要由自己的系统记录异常。

• API补齐缺失数据： 发现 Webhook 丢失或处理失败时，可以再通过美洽 API 查询对应对话、客户或工单数据补齐，同时保存请求唯一 ID 做去重。

常见问题