为实时签名设置网络钩子。+更新

Webhooks 允许您收到关于您在 Sign.Plus 中信封状态的实时更新。 这篇文章将带着你设置和处理您的 Sign.Plus 集成的 web 钩子。

第 1 步：创建一个Web 钩子

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

1. 决定您想要接收网络钩子通知的目标 URL。 这应该是您服务器上为处理传入的 POST 请求设置的端点。
2. 选择您想要跟踪的事件 (s) 。 Plus 提供以下Webhook 事件：
   • 信封已完成 - 信封完成时
   • 信封过期的 - 信封过期时
   • 信封拒绝了 - 当信封被拒绝时
   • 信封_无效 - 当信封无效时
3. 使用 Sign.Plus API 来创建 webhook。 您需要指定您的目标URL和您想要跟踪的事件。

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

第 2 步：处理 webhook 记事

一旦您设置了您的 webhook，Sign.Plus 将在跟踪事件发生时向您指定的 URL 发送POST 请求。 下面是您需要知道的处理这些通知的情况：

1. 请求方式： 所有Webhook 通知都以 HTTP POST 请求发送。
2. 有效载荷结构： webhook 有效载荷是一个包含两个主要部分的 JSON 对象：
   • hook: Contains metadata about the webhook itself.
   • 数据: 包含触发事件的信封信息。
3. Payload Examples: Here are examples of payloads for different events:
   // 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。

A. 最佳做法

1. 安全性： 确保您的 webhook 端点是安全的。 考虑为您的 webhook URL执行身份验证。
2. Idempotency: Design your webhook handler to be idempotent. 这意味着它应该产生相同的结果，即使相同的 webhook 收到了多次。
3. 错误处理： 在您的 webhook 处理逻辑中实现了强大的错误处理。

通过遵循本指南，您将能够有效地设置和处理 Web 钩子。 允许您的应用程序实时收到关于签名中信封状态的更新。 大腿。