# 通过 Webhook 接收 Drime Sign 事件

当文档在 Drime Sign 中被发送、查看、签署、拒绝或完成时，在您的服务器上收到 HTTP 通知，并确认每次调用都来自 Drime。

更新于：2026-10-21  
来源：https://drime.cloud/zh-cn/support/integrations-and-api/sign-webhooks

Webhook 会让 Drime 在您的签署请求每次发生变化时调用您的服务器。每次调用都是一个 JSON `POST`，并用密钥签名，让您的服务器可以确认调用来自 Drime。

## 添加 Webhook

1. 打开**设置** \> **开发人员** \> **Webhook**。

   您也可以从签署中点击**偏好设置**，打开 **Webhook** 标签页，然后点击**打开开发者设置**。

2. 点击**添加 Webhook**。

3. 在**端点 URL** 中，输入接收调用的服务器地址。

4. 在**事件**下，将每个要接收的事件设为**打开**，然后点击**创建 Webhook**。

   界面会显示**已创建 Webhook**。

5. 请立即复制密钥，然后点击**完成**。

   **Webhook 密钥，请立即复制**：密钥只会显示这一次。请将它存放在安全的地方。

![新建 Webhook 的对话框，显示一个示例服务器的端点 URL 和 Drime Sign 事件列表](https://drime.cloud/media/01M5F06YR56KKN1FP1T6WCV3QW/8adc8de810cf-web-sign-webhook-create.png)

## 事件

| 事件 | 发送时机 |
| --- | --- |
| `envelope.sent` | 文档已发送以供签署 |
| `envelope.completed` | 所有签署人都已签署 |
| `envelope.declined` | 有签署人拒绝，因此文档被拒绝 |
| `signer.viewed` | 签署人打开了文档 |
| `signer.signed` | 签署人已签署 |
| `signer.declined` | 签署人已拒绝 |
| `template.created` | 已创建模板 |

## Drime 发送的内容

每次调用都带有以下请求头：

- `X-Drime-Event`：事件，例如 `envelope.completed`；
- `X-Drime-Delivery`：发送的编号；
- `X-Drime-Signature`：`sha256=` 加上用您的密钥计算的原始请求体 HMAC SHA-256。

JSON 请求体包含 `event_type`、`event_uuid`、`timestamp` 和 `data`，也就是相关文档及其签署人。**Webhook** 部分中的**请求范例与签章验证**提供了完整示例。

同一次发送可能会多次送达：请使用 `event_uuid`，确保每个事件只处理一次。

## 验证签名

使用您的密钥计算原始请求体的 HMAC SHA-256，然后与 `X-Drime-Signature` 请求头比对。以 Node.js 为例：

```js
import crypto from 'node:crypto';

function isFromDrime(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return header.length === expected.length && crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}
```

请使用收到时的原始请求体，不要先进行 JSON 解析。

## 测试并跟踪发送情况

- **发送测试**会发送一个测试事件：**测试事件已排入队列，请查看发送记录**。
- **发送记录**会列出每次调用及其状态：**成功**、**待处理**或**失败**。**重新发送**可再次发送某次发送。
- 如果您的服务器没有响应或返回错误，Drime 会重试，在大约 34 小时内最多尝试 10 次。
- **打开** / **关闭**开关可暂停 Webhook 而不删除：界面会显示**已暂停 Webhook**，重新开启时则显示**已激活 Webhook**。

## 更换密钥或删除 Webhook

- **更换密钥**会创建新的密钥。应用会警告（**要重新产生密钥吗？您目前的密钥将立即失效。**），请立即更新您的服务器。
- **删除**会移除 Webhook：**要删除此 Webhook 及其发送记录吗？**

## 遇到问题时

| 您看到的情况 | 处理方法 |
| --- | --- |
| **请输入端点 URL** | 创建 Webhook 前，请先输入您服务器的地址。 |
| **请至少激活一个事件** | 在**事件**下至少选择一个事件。 |
| 发送一直显示**失败** | 请确认您的服务器可以从互联网访问，并返回成功代码。然后点击**重新发送**。 |
| 您的服务器拒绝签名 | 请用原始请求体计算 HMAC，而不是解析后的 JSON，并使用当前的密钥。点击**更换密钥**后，旧密钥就会失效。 |

## 后续步骤

- [开发应用或接入 Webhook](https://drime.cloud/zh-cn/support/integrations-and-api/build-an-integration)
- [创建 API 令牌](https://drime.cloud/zh-cn/support/integrations-and-api/api-tokens)
- [已签署文档的审核证书包含哪些内容](https://drime.cloud/zh-cn/support/sign/audit-trail-and-certificate)