系统集成传出 Webhook 指南

传出 Webhook 功能让 ABC Sales Bot 能够在特定事件发生时，向你的外部系统发送实时通知。对于需要在多个平台之间保持数据同步的企业来说，这项功能至关重要，例如 CRM、库存管理系统或自定义的数据分析仪表板。

你不必持续轮询我们的 API 来检查变更（这样效率很低），而是可以订阅事件。当事件发生时（例如潜在客户被创建或更新），我们会立即将相关数据推送到你提供的 URL。

主要使用场景

• 实时 CRM 同步： 在潜在客户于 ABC Sales Bot 中创建或修改的那一刻，立即在你的 CRM（例如 Salesforce、HubSpot）中创建或更新联系人
• 自动化履约与运营： 在你的内部系统中触发一个流程，例如将新的潜在客户分配给区域销售团队，或在你的营销平台上启动欢迎序列
• 集中式数据仓库： 将所有潜在客户和对话数据推送到集中的数据分析平台（如 Google BigQuery 或自定义仪表板），以进行高级报表分析
• 自定义通知： 当重要事件发生时（例如潜在客户被升级转人工），向 Slack 或 Microsoft Teams 等团队沟通平台发送定制通知

如何配置传出 Webhook

设置 Webhook 的流程非常简单。

1. 从主菜单前往 Outgoing Webhooks（传出 Webhooks）标签
2. 点击 Create Webhook（创建 Webhook）按钮
3. 会出现一个配置窗口，填写以下详细信息
4. 点击 Create Webhook 保存并启用它

配置字段：

• Webhook URL（必填）： 最重要的字段。输入你的外部系统中已准备好接收数据的唯一 URL。
• Event Types（事件类型）： 选择你想订阅的特定事件。你可以订阅单个事件，也可以订阅全部事件。
• Custom Headers（自定义标头，可选）： 为你的 Webhook 请求添加静态标头值，可用于你服务器上的身份验证或路由。
• Max Retries（最大重试次数）： 当你的服务宕机或返回错误时，我们尝试重新发送事件的次数。重试采用指数退避策略，以避免压垮你的系统。
• Max Concurrency（最大并发数）： 我们同一时间可以发送的 Webhook 数量。默认值通常足以应对大多数使用场景。

主要事件类型包括：

• leads_created
• leads_updated
• leads_deleted
• leads_escalation_requested
• conversation_created

你可以创建多个 Webhook，例如你想把不同的事件发送到不同的系统。

安全性：使用密钥验证负载

为了确保你的服务器收到的请求确实来自 ABC Sales Bot，我们会对每个 Webhook 负载进行签名。

查看密钥

1. 在 Outgoing Webhooks 页面上，点击你的 Webhook 旁边的三点菜单，选择 Edit（编辑）
2. 点击 Show Secret Key（显示密钥）
3. 该密钥是你的 Webhook 独有的。你必须在服务器上使用该密钥来验证传入负载的签名

验证逻辑

我们会在每个请求的标头中包含一个加密签名。你的服务器可以使用共享的密钥，根据请求主体重新计算签名。如果两者一致，你就可以确定该请求是真实的且未被篡改。

重新生成密钥

如果你认为密钥已经泄露，可以随时重新生成。重新生成后，请记得同步更新你服务器上的密钥。

理解负载

当事件被触发时，我们会向你的 URL 发送一个带有 JSON 主体的 POST 请求。负载中始终包含：

• event_type： 发生的事件名称（例如 leads_updated）
• company_id： 你公司的唯一标识符
• 相关的对象数据： 对于 leads_created 和 leads_updated，这是完整的潜在客户对象；对于 leads_deleted，我们只发送 lead_id，因为完整对象已不存在

故障排除：Webhook 日志

为了诊断 Webhook 投递问题，每个端点都提供了详细的日志。

1. 在主列表中点击一个已配置的 Webhook
2. 这会打开 Webhook Log（Webhook 日志）视图，显示发送到该 URL 的所有事件历史

对于每个事件，你可以看到：

• 状态： 成功显示绿色勾号，失败显示红色警告
• 尝试次数： 已进行的重试次数
• 请求时长： 你的系统响应所花费的时间。这对于发现你这一端的性能缓慢或超时问题很有帮助
• 查看详情： 点击可查看我们发送的确切请求负载，以及从你的服务器收到的响应主体（和状态码）。这对调试非常有价值，因为一旦出错，它会准确地告诉你问题出在哪里