设置 webhook 以获取 Sign.Plus 的实时更新

Webhook 可让您实时获取 Sign.Plus 中信封状态的更新。本文将引导您完成为 Sign.Plus 集成设置和处理 webhook 的流程。

步骤 1：创建 webhook

要开始接收实时更新，您首先需要在 Sign.Plus 中创建一个 webhook。方法如下：

1. 确定您要接收 webhook 通知的目标网址。这应该是您服务器上设置为处理传入 POST 请求的端点。
2. 选择您要追踪的事件。Sign.Plus 提供以下 webhook 事件：
   • envelope_completed

      - 当信封完成时

   • envelope_expired

      - 当信封过期时

   • envelope_declined

      - 当信封被拒签时

   • envelope_voided

      - 当信封被作废时

3. 使用 Sign.Plus API 创建 webhook。您需要指定目标网址以及要追踪的事件。

有关如何使用 Sign.Plus API 创建 webhook 的详细信息，请参阅创建 webhook 端点文档。

步骤 2：处理 webhook 通知

设置好 webhook 后，每当追踪的事件发生时，Sign.Plus 都会向您指定的网址发送 POST 请求。以下是处理这些通知时需要了解的内容：

1. 请求方法：所有 webhook 通知均以 HTTP 

   POST

    请求发送。

2. 有效负载结构：webhook 有效负载是一个包含两个主要部分的 JSON 对象：
   • hook

     ：包含有关该 webhook 本身的元数据。

   • data

     ：包含触发该事件的信封的相关信息。

3. 有效负载示例：以下是不同事件的有效负载示例：

   // ENVELOPE_DECLINED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_declined",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}

// ENVELOPE_COMPLETED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_completed",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}

// ENVELOPE_EXPIRED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_expired",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}

// ENVELOPE_VOIDED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_voided",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}
4. 处理通知：当您的服务器接收到 webhook 通知时：
   • 验证有效负载，确保其为有效的 webhook 通知。
   • 从有效负载中提取相关信息。
   • 根据事件类型执行必要的操作（例如更新数据库、通知用户、触发其他流程）。

   • 发送 

     200 OK

      响应以确认已收到该 webhook。

Sign.Plus webhook 仅会从以下授权 IP 地址发送：
34.65.253.117
34.65.146.131

最佳实践

1. 安全性：确保您的 webhook 端点是安全的。请考虑为您的 webhook 网址实现身份验证。
2. 幂等性：设计您的 webhook 处理程序使其具有幂等性。这意味着即使多次收到相同的 webhook，也应产生相同的结果。
3. 错误处理：在您的 webhook 处理逻辑中实现健全的错误处理机制。

按照本指南，您将能够有效地设置和处理 webhook，使您的应用程序能够实时接收 Sign.Plus 中信封状态的更新。