Deskhero
中文
免费试用

← Back to articles

服务台 Webhook 的作用及其重要性

服务台 Webhook 的作用及其重要性

帮助台 webhook 是一种出站 HTTP 请求，会在工单事件发生时将其发送到另一个系统。它可以触发提醒、自动化流程或数据同步，而无需频繁轮询。要实现可靠的集成，仍需进行谨慎配置：验证每个请求、快速确认交付，并在让端点接收生产流量之前完成测试。

简要总结：

  • 与频繁轮询相比，webhook 可以以更低延迟和更少的 API 调用传递工单更新。
  • 配置通常包括一个公开的 HTTPS 端点、事件订阅、请求验证，以及使用具有代表性的事件进行测试。
  • 安全控制取决于服务提供商，但通常包括 HTTPS、签名或令牌验证、密钥轮换，以及遵循最小权限原则进行处理。
  • 接收方应通过幂等处理，并与当前状态进行协调，来应对重复或乱序事件。
  • Deskhero 目前不会发送出站 webhook。当自定义集成需要工单数据时，可以轮询其 REST API。

目录

帮助台 webhook 如何工作：事件、POST 与载荷

帮助台 webhook 从某个事件开始。有人创建工单、用户更改工单状态、客户回复，或优先级发生变化。如果平台为该事件提供 webhook，并且你已订阅该事件，平台就会向你注册的 URL 发送 HTTP 请求。与按照固定计划进行轮询不同，接收方不必持续询问是否有任何变化。Webhook 载荷通常采用 JSON 格式，不过具体格式和字段取决于服务提供商。

Webhook JSON 载荷字段示意图

工单创建载荷可能包括工单 ID、状态、优先级、请求者详细信息，以及导致该事件发生的相关信息。不要假设这些字段一定存在，或始终保持相同的结构。应以服务提供商当前的事件架构为准，并在使用载荷之前对其进行验证。

与轮询相比，实际差异在于时效性和控制方式。Webhook 可以在事件发生后不久通知你的接收方，而轮询程序则要等到下一次运行时才能发现变化。当更新并不紧急时，轮询通常更简单。当低延迟很重要，并且服务提供商支持你所需的事件和安全控制时，webhook 会很有用。

帮助台 webhook 的最佳使用场景有哪些？

当另一个系统需要及时响应工单事件时，webhook 最有价值。常见示例包括：

  • 渠道提醒。 如果帮助台发出相应事件，且接收集成支持该事件，新建或紧急工单可以触发协作工具中的通知。
  • CRM 更新。 可以将选定的工单活动复制到客户记录中，使支持团队和销售团队获得相关背景信息。
  • 升级触发器。 紧急事件可以在值班系统中创建事故或提醒。
  • 分析数据接入。 工单事件可以进入队列或数据管道，以便后续进行报告分析。
  • 跨系统协作。 工单事件可以为另一个团队创建或更新相关工作项。

这些工作流仍需要明确的负责人和故障处理机制。Webhook 只是交付机制。接收系统仍负责验证事件、应用业务规则，并在下游服务不可用时进行恢复。

如何设置帮助台 webhook？

具体流程因平台而异，但典型设置通常包括以下步骤：

  1. 阅读服务提供商的文档。 确认可用的事件类型、载荷架构、身份验证方式、超时时间、重试策略以及交付日志功能。
  2. 公开一个 HTTPS 端点。 构建一个能够接受服务提供商请求格式的路由。许多 webhook 系统使用携带 JSON 的 POST 请求，但你的实现应遵循文档中规定的契约。
  3. 注册端点和事件。 通过平台的管理界面或 API 添加 URL，然后仅订阅集成所需的事件。
  4. 配置请求验证。 如果服务提供商提供签名密钥或验证令牌，请将其存储在密钥管理器或受保护的环境变量中。绝不要将其硬编码到源代码管理中。
  5. 及时确认。 在开始缓慢的下游工作之前，先返回预期的成功响应。Stripe 的 webhook 文档建议在端点返回成功响应后，再延后执行复杂处理。
  6. 上线前进行测试。 使用服务提供商提供的测试事件或开发工作区。安全的转发工具可以在本地开发期间提供帮助，但不要让未受保护的开发服务接收生产流量。
  7. 检查交付结果。 如果服务提供商提供交付日志，请利用它将已发送的事件与接收方的响应和处理记录进行比较。

快速确认可以降低服务提供商将响应缓慢的接收方判定为交付失败的可能性。在进一步处理之前先将经过验证的事件加入队列，也能让你更容易重试自己的工作，而不必要求发送方重新发送事件。

如何保护帮助台 webhook 端点？

Webhook URL 可以从网络外部访问，因此接收方不能仅仅因为请求到达了正确路径，就信任该请求。

使用具有有效证书和当前受支持 TLS 配置的 HTTPS。然后实现服务提供商文档中规定的验证机制。该机制可能是 HMAC 签名、验证令牌、非对称签名或其他方案。签名验证通常需要精确的原始请求正文，因此应在解析或转换请求正文之前完成验证。

如果服务提供商的方案支持时间戳或唯一事件 ID，请防范重放攻击。使用恒定时间比较来比较签名，拒绝无效请求，并避免将密钥或个人数据写入应用日志。在支持的情况下轮换密钥；如果轮换期间旧密钥和新密钥必须同时有效，请保留有文档记录的重叠流程。

只为 webhook 处理程序授予其所需的权限。如果服务提供商公布了稳定的源 IP 范围，允许列表可以作为额外控制措施，但不应替代请求验证。谨慎应用速率限制，监控失败情况，并且只保留工作流所需的事件数据。

如何保护帮助台 webhook 端点？概览示意图

如何测试和调试帮助台 webhook？

首先要将交付问题与处理问题区分开来。确认服务提供商是否发送了事件、请求是否到达你的端点、端点返回了什么响应，以及已接受的事件是否完成了下游工作。

  • 在可用的情况下使用服务提供商提供的测试事件，然后在非生产工作区中测试具有代表性的真实事件。
  • 记录事件 ID、事件类型、接收时间、验证结果、响应状态和处理结果。对密钥进行脱敏，并尽量减少存储的个人数据。
  • 使用平台的交付日志检查响应代码和重试情况。Zendesk 记录了其 webhook 服务的活动和调用详细信息，可用于故障排查。
  • 将服务提供商的交付记录与反向代理日志及应用日志进行比较。缺少请求头或正文发生变化，可能说明中间件或代理配置存在问题。
  • 测试超时、无效签名、重复事件 ID、下游服务不可用，以及以意外顺序交付的事件。

专业提示： 保留足够的结构化交付历史，以便追踪故障，但应设置保留期限；除非确实需要且已得到适当保护，否则不要记录原始载荷。

应如何处理重复或乱序的 webhook 事件？

不要假设每个事件都会恰好交付一次，也不要假设事件总会按照创建顺序到达。交付行为因服务提供商而异，而重试可能会产生重复事件。Hookdeck 的概览比较了至少一次和恰好一次的交付方式。

让处理程序具备幂等性。当服务提供商提供稳定的事件 ID 时，请记录该 ID，避免同一操作被应用两次。对于状态变更，如果服务提供商定义了事件时间戳或序列值，请使用这些信息；当正确性比处理每个中间状态更重要时，则获取资源的当前状态。使用有限次数的重试和退避策略，将失败的工作加入队列，并将持续失败的任务发送到可供审核的死信队列或等效流程中。

Deskhero 的 API 选项

Deskhero 目前提供带有个人 bearer token 的 REST API，但不会发送出站 webhook。需要 Deskhero 工单数据的集成必须以适当的时间间隔轮询 API，并遵守其速率限制。这与上文所述的事件交付模式不同，因此应针对检查点、分页、去重，以及轮询作业失败后的恢复进行规划。

在 webhook 与轮询之间进行选择

应根据你正在集成的系统进行选择，而不要假设每个帮助台都同时支持这两种模式。Webhook 可以缩短发现变化的延迟，但需要一个公开的接收方，并且必须谨慎处理交付。轮询需要调度和检查点逻辑，但可能更容易运维和协调。

Deskhero

Deskhero 可以将 Gmail 或 Microsoft 365 邮箱转变为共享帮助台，同时保留公司的现有电子邮件地址。它提供双向电子邮件同步、内置工单自动化、基于工作区知识生成的 AI 回复草稿，以及用于自定义集成的 REST API。Deskhero 的自动化流程会在新工单创建时运行；它们不能替代出站 webhook。Shopify 用户还可以连接 Shopify integration，在 Deskhero 中查看相关的订单和客户信息。无需信用卡即可享受 30 天免费试用。

在哪里可以进一步了解 webhook 标准？

不存在一种单一的 webhook 标准，能让每个服务提供商都以相同方式运行。请将服务提供商的文档作为事件架构、验证、重试和超时方面的权威依据。Notion 的 webhook 文档提供了订阅验证和事件交付的一个具体示例。

来源

常见问题

Webhook 究竟是什么？

Webhook 是一个系统在定义的事件发生后，向注册 URL 发送的 HTTP 请求。它携带相关信息，使接收系统能够决定如何作出响应。

使用 webhook 有哪些缺点？

Webhook 需要一个安全且可从公网访问的接收方。集成还必须考虑服务提供商特定的验证机制、重试、重复事件、可能发生的乱序、停机、监控，以及事件架构的变更。

Webhook 与 API 有什么区别？

API 通常允许你的软件请求数据或触发操作。Webhook 则允许另一个系统向你的接收方发送事件。许多集成会同时使用两者：由 webhook 宣布发生了变化，再由 API 提供资源的当前数据。

可以举一个帮助台 webhook 的例子吗？

支持出站 webhook 的帮助台可能会向你的接收方发送工单创建事件。在验证请求后，你的集成可以向团队频道添加通知，或更新 CRM 记录。Deskhero 目前不会发送出站 webhook，因此自定义 Deskhero 集成必须改为轮询其 REST API。