BoldSign Webhooks：App vs Account——如何选择

Source: Dev.to

抱歉，我需要您提供要翻译的具体文本内容（除代码块和 URL 之外）。请把文章的正文粘贴在这里，我会按照要求保留源链接并将内容翻译成简体中文。

简短回答

What you’ll get from this guide

• 对 BoldSign webhook 工作原理的简要说明。
• 对应用级别 vs. 账户级别 webhook 的清晰比较。
• 何时选择每种选项的指导，以及实际场景。
• 可用于您架构的决策框架。
• 可靠且安全的 webhook 处理的技术最佳实践。

Source: …

BoldSign Webhooks 工作原理

本节从宏观上解释了 BoldSign webhook 是什么以及它们为何对保持集成同步至关重要。

BoldSign webhook 是 HTTP POST 请求，BoldSign 在订阅的事件发生时会发送到您的端点。

这些事件涵盖完整的签署生命周期，包括：

• 文档事件： 已发送、已查看、已签署、已完成、已拒签、已过期。
• 身份验证事件： 身份验证失败、身份验证已发起。

完整列表请参见 可用的 Webhook 事件 – API 文档。

与其轮询 BoldSign API，BoldSign 会在重要状态变化时直接调用您的 webhook 端点。

为什么使用 webhook？

• 立即对关键变化作出响应。
• 消除或最小化 API 轮询。
• 自动化工作流和后端更新。
• 保持准确、实时的文档跟踪。

完整的负载结构和示例 JSON，请参考 示例事件数据。

要配置您的第一个 webhook，请参见 设置 webhook。

应用级别 vs. 账户级别 Webhook：关键区别

Source: …

应用级 Webhook

它们是什么

应用级 Webhook 只会为通过特定 OAuth 应用在 BoldSign 中创建或发送的文档发送事件。如果您有多个 OAuth 应用（按客户或按环境划分），每个应用都可以拥有自己的 webhook 配置和 URL。

何时适合使用应用级 Webhook

当您满足以下情况时，请选择应用级 Webhook：

• 构建多租户 SaaS 解决方案，需要对每个客户进行隔离。
• 需要为测试环境和生产环境分别设置 webhook。
• 需要将客户端特定的事件路由到不同的 CRM、ERP 或后端系统。
• 想要在不影响其他集成的情况下关闭或调整某个集成。

简而言之：当您对隔离性和路由控制有较高要求时，应用级是正确的选择。

应用级示例场景

1. 一个 SaaS 平台为数百个客户集成 BoldSign。
2. 每个客户（租户）都有自己的 BoldSign OAuth 应用。
3. 对于每个 OAuth 应用，SaaS 定义一个指向该租户集成流水线的应用级 webhook 端点。
4. 当文档签署完成时，BoldSign 只会将事件发送到与该租户应用关联的 webhook。
5. 租户的 CRM 或后端仅接收到其自身的文档事件。

结果： 实现了每个客户的清晰分离、明确的路由，并为多租户系统提供了可扩展的模式。

账户级 Webhook

它们是什么

账户级 Webhook 适用于整个 BoldSign 账户。您只需配置 一个 webhook 端点，BoldSign 会将该账户的 所有 文档事件发送到该 URL。该账户中所有文档的活动都会流入同一个中心 webhook。

何时适合使用账户级 Webhook

如果满足以下情况，请选择账户级 Webhook：

• 您只有一个团队或内部系统需要监控所有活动。
• 您更看重简洁性，倾向于使用单一的集成点。
• 您不需要按客户进行隔离（例如，单个组织使用 BoldSign）。

何时选择账户级 Webhook

使用 BoldSign 的 团队或部门——无论是人力资源、法务、财务、销售或其他任何团队——可能更倾向于在一个地方接收并处理所有事件。

• 您希望在一个地方接收并处理所有事件。
• 您正在构建内部仪表盘或集中监控系统。
• 您希望配置尽可能简单，减少移动部件。

简而言之： 当简洁性和完整可视性比严格的租户隔离更重要时，账户级是理想选择。

账户级示例场景

• 人力资源团队使用 BoldSign 发送录用信、保密协议和入职文件。
• 他们配置了一个账户级 webhook，将 所有 事件发送到其 HR 系统。
• HR 系统监听 “completed”（完成）、“declined”（拒绝） 和 “expired”（过期） 事件，并实时更新候选人状态。

结果： 一个集成，一个 webhook，完整可视化所有 HR 文档活动。

决策指南：应选择哪种 Webhook 级别？

在许多实际场景中，团队会先选择 Account‑Level 以求简便。随着业务发展为多租户或更复杂的集成模式，便会为需要隔离的用例引入 App‑Level。

您 并非永久锁定在单一模式。可以：

• 从 Account‑Level 开始您的首个集成。
• 后续为每个租户或产品引入 App‑Level Webhook。
• 若架构需要，可同时并行运行两种类型。

这种选择在实际工作流中的体现

人力资源与员工入职

• 场景： 人力资源部门使用 BoldSign 发送录用信、保密协议（NDA）和雇佣合同。
• Webhook 级别： 账户级（Account‑Level）
• 实现方式： 单一 webhook 端点向 HR 系统推送所有文档事件（已发送、已查看、已签署、已拒绝）。
• 影响： 自动在 HR 仪表盘更新状态，触发入职工作流，确保没有候选人被遗漏。

多租户 SaaS 的销售合同管理

• 场景： 一家 SaaS 供应商为众多独立客户管理合同。
• Webhook 级别： 应用级（App‑Level）
• 原因： 每个客户都有自己的 OAuth 应用，因此每个租户的事件都会发送到其专属的 webhook 端点。
• 影响： 各客户的 CRM 或后端仅收到自己的数据，简化了数据隔离，并能在数百个账户之间实现可扩展性。

法律合规与审计追踪

• 场景： 律师事务所需要为每一次签署事件提供可靠、详细的审计追踪。
• Webhook 级别： 可为应用级（App‑Level）或账户级（Account‑Level），取决于集成设计。
• 原因： Webhook 实时推送完成、拒绝或签署事件，可记录到合规系统中。
• 影响： 自动生成可验证的审计追踪，降低审计期间的人工工作量和风险。

内部运营仪表盘

• 场景： 公司希望拥有一个中心仪表盘，查看跨团队的所有文档。
• Webhook 级别： 账户级（Account‑Level）
• 原因： 单一 webhook 将所有文档事件流式传输到数据仓库或分析服务。
• 影响： 通过最少的配置实现跨团队可视化和报告。

BoldSign Webhooks 技术最佳实践

签名验证

• 每个 webhook 请求都会包含 X‑BoldSign‑Signature 头部。
• 使用 HMAC‑SHA256 和你的 webhook 密钥来验证该签名。
• 对签名校验失败的请求予以拒绝。

快速、可预测的响应

• 对成功处理的请求在 10 秒 内返回 HTTP 200。
• 如果处理过程较重，应该将工作放入后台任务队列，并快速返回 200。

重试处理

• BoldSign 会对投递失败的请求进行指数退避重试。
• 重试通常从约 1 分钟 开始，最长可持续 24 小时。
• 设计你的处理程序为 幂等，以防重试事件导致数据损坏或产生重复。

完备的日志记录

• 记录传入的 事件 ID、类型和时间戳。
• 记录验证失败和处理错误，并提供足够的细节以便调试。
• 将日志聚合到你常用的系统（CloudWatch、ELK、Datadog 等），便于追踪问题。

环境分离

• 如果在分阶段（staging）和生产（production）环境使用 App‑Level，务必清晰分离 密钥、URL 和日志。
• 切勿将 staging 环境的 webhook 发送到生产系统（或反之）。

结论

在 BoldSign 中选择合适的 webhook 级别更多的是关于 架构，而不是语法：

• 选择应用级别（App‑Level）Webhook，如果您需要精确控制、租户隔离或环境分离。当您支持多个客户、维护独立环境，或希望对每个 OAuth 应用进行细粒度路由时，它们是理想选择。
• 选择账户级别（Account‑Level）Webhook，如果您追求简洁、集中可视化，只需管理一个 webhook 端点。它们适用于单一团队、内部仪表盘以及直接的集成场景。

两种方式都能为您提供 实时、事件驱动的工作流，无需轮询。正确的选择取决于您的系统、团队和集成的结构方式。

如需深入了解配置、负载格式、事件类型及安全细节，请参考 BoldSign 开发者文档。

其他资源

• 欲了解更多细节，请查看官方的 BoldSign Webhooks 文档。
• 您可以安全地进行 30 天免费试用。
• 需要帮助设计适合您集成的方案吗？请通过 BoldSign 支持门户 联系我们。

相关博客

• 简化会计事务所的签署政策和流程（BoldSign）
• BoldSign 在银行开户中的帮助
• BoldSign 移动应用中的文件上传：您需要了解的一切

注意： 本博客最初发布于 boldsign.com。