如何通过 Webhook 将 CRM 接入全渠道收件箱

本指南面向希望让 CRM 与全渠道收件箱共享同一个客户视图的 CTO、解决方案架构师和 CRM 管理员。内容介绍应该同步哪些事件、如何构建能够应对重试和重复的 Webhook 接收端、如何在 WhatsApp、Instagram 和电子邮件之间匹配联系人，以及哪些隐私规则会影响设计。

CRM 与全渠道收件箱之间应该交换什么？

收件箱应该告诉 CRM：谁联系了你、通过哪个渠道、为了什么事、结果如何。CRM 则应该告诉收件箱：客户是谁、归谁负责，以及坐席需要了解哪些背景信息。

从能够支撑一个真实工作流的最小数据集开始。把每条消息正文都同步到 CRM 很少有必要，还会增加隐私风险。

应该订阅哪些 Webhook 事件？

要订阅生命周期事件，而不只是消息。不同平台的具体事件名称各异，请将它们对应到下列类别：

• 会话已创建 — 客户在任一渠道发来的第一条消息。
• 收到消息 — 客户发来的消息，附带渠道和发送者标识符。
• 消息已发送 — 坐席或模板发出的外发消息。
• 消息状态 — 已发送、已送达、已读或失败（以渠道实际回报的为准）。
• 会话已分配 — 负责人或队列发生变化。
• 会话已解决或重新打开 — 状态变更。
• 联系人已更新 — 收件箱中的标识符或属性发生变化。

对于 WhatsApp，Meta 自己的 Webhook 会把入站消息和外发消息的状态更新推送给平台；随后你的收件箱服务商再把它自己的事件开放给你的系统。

如何构建可靠的 Webhook 接收端？

快速接收、验证、只存一次、稍后处理。大多数送达问题都源于在 Webhook 请求内部处理 CRM 工作。

接收端设计步骤

1. 每个环境提供一个 HTTPS 端点，例如 /webhooks/inbox。
2. 验证真实性。 检查签名（通常是按 RFC 2104 定义，用共享密钥对原始请求体计算 HMAC）或发送方文档中说明的令牌。请在解析 JSON 之前，基于原始字节进行计算。
3. 检查时效性。 如果带有时间戳，就拒绝超出较短容忍范围的事件，以限制重放。
4. 去重。 把事件 ID 插入带有唯一约束的表。如果因为 ID 已存在而插入失败，就返回成功并停止。
5. 入队。 把事件放入队列，并立即返回 2xx 响应。
6. 异步处理。 由工作进程读取队列，匹配联系人，并使用 upsert 写入 CRM。
7. 退避重试。 如果 CRM 宕机，就从你自己的队列中按指数退避重试；不要依赖发送方的重试。
8. 死信队列。 多次失败后，把事件移入死信队列并提醒相关人员。
9. 对账。 运行定期任务，将最近的收件箱会话与 CRM 记录比对，并通过收件箱 API 补齐缺失的数据。

为什么幂等性和顺序很重要

Webhook 发送方在没有及时收到成功响应时通常会重试，这使得送达是“至少一次”。同一个事件可能到达两次，“已解决”事件也可能先于最后一条“收到消息”事件到达。可以这样处理：

• 把事件 ID 作为去重键。
• 在 CRM 中使用以会话 ID 或消息 ID 为键的 upsert。
• 比较事件时间戳或序列号，忽略更旧的状态。

当你的 CRM 工作流调用收件箱 API 发送消息时，如果 API 支持，请传入幂等键；关于 Idempotency-Key HTTP 头的 IETF 草案描述了这种常见模式。

如何跨渠道匹配联系人？

按规范化的标识符匹配，优先使用确定性的匹配，并把有歧义的情况交给人工处理。

决策规则：

1. 恰好一个精确匹配：关联。
2. 没有匹配：创建线索或带来源渠道的“未匹配联系人”。
3. 多个匹配：标记给坐席处理，不要自动合并。
4. 客户在对话中确认了另一个标识符：关联，并附上证据备注。

如何在 CRM 集成中处理数据隐私？

只传输各系统所需的数据，记录原因，并让删除操作在两个系统中都能生效。

• 数据最小化。 在 CRM 中存储会话链接、结果和摘要；除非有明确的目的，否则完整记录保留在收件箱中。
• 合法依据与授权。 按渠道记录营销 opt-in；客户服务对话不等于同意接收营销模板。
• 保留期限。 让收件箱、CRM、队列和日志的保留期限保持一致；Webhook 负载日志常常被遗忘。
• 访问控制。 限制谁可以在 CRM 中查看消息内容和附件。
• 删除与查阅请求。 让一个系统中的请求同步传递到另一个系统。
• 跨境传输。 核实每个系统把数据存储在哪里。GDPR 适用于欧盟境内个人的个人数据，阿联酋和沙特阿拉伯也有各自的个人数据保护法律；请向相关监管机构和你的法务团队确认当前的义务。

参考架构是什么样的？

用文字描述，流程是：渠道到收件箱，收件箱到接收端，接收端到队列，队列到工作进程，工作进程到 CRM，CRM 工作流再回到收件箱 API。

实操案例：吉达的一家连锁诊所

“Wahat Clinics”是沙特阿拉伯的一家虚构医疗集团，使用 CRM 管理患者预约，并用收件箱处理 WhatsApp 和电子邮件。

• 一位患者通过 WhatsApp 发来消息。收件箱发出会话已创建事件；接收端对其验证、存储并入队。
• 工作进程把号码规范化为 E.164，找到唯一的患者记录，并记录一条活动，其中包含指向会话的链接，而不是消息文本。
• CRM 显示该患者的首选语言是阿拉伯语，并推送给收件箱，由收件箱将会话路由到阿拉伯语队列。
• 在 CRM 中预约成功后，工作流调用收件箱 API 发送已审核的实用型（Utility）模板确认消息，并以预约 ID 作为幂等键传入，这样重试就不会发出两条确认。
• 收件箱的“消息已送达”事件会更新预约记录。

常见错误有哪些？

• 在 Webhook 请求内部写入 CRM， 导致超时、重试和重复。
• 没有去重， 产生重复的活动记录和联系人。
• 用未规范化的手机号匹配， 导致 +971 和以 0 开头的格式永远对不上。
• 按姓名或部分匹配自动合并。
• 没有目的或保留规则就把所有消息内容复制到 CRM。
• 没有对账， 一次丢失的事件就会变成永久性的数据偏差。
• 把密钥写进源代码， 且没有轮换计划。

OmniChannels.ai 如何提供帮助

由 BroadNet Technologies 提供支持的 OmniChannels.ai，把 WhatsApp、Instagram、Messenger、Telegram 和电子邮件的会话汇集到同一个 Omni Inbox，支持坐席分配和打标签，并通过 Meta Embedded Signup 开通 WhatsApp，提供带变量、媒体和按钮的已审核模板。在 CRM 集成方面，REST API 公开提供文档并附有 OpenAPI 3.1 规范，Webhook 以统一规范化的格式报告送达状态（SENT、DELIVERED、READ、FAILED 等）。带筛选和 CSV 导出功能的送达报告有助于对账。请从开发者页面开始。