# 透過 Webhook 接收 Drime Sign 事件

當文件在 Drime Sign 中被傳送、檢視、簽署、拒絕或完成時，在您的伺服器上收到 HTTP 通知，並確認每次呼叫都來自 Drime。

更新於：2026-10-21  
來源：https://drime.cloud/zh-tw/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-tw/support/integrations-and-api/build-an-integration)
- [建立 API 權杖](https://drime.cloud/zh-tw/support/integrations-and-api/api-tokens)
- [已簽署文件的稽核憑證包含哪些內容](https://drime.cloud/zh-tw/support/sign/audit-trail-and-certificate)