透過 Webhook 接收 Drime Sign 事件

Webhook 會讓 Drime 在您的簽署要求每次發生變化時呼叫您的伺服器。每次呼叫都是一個 JSON POST，並以密鑰簽章，讓您的伺服器可以確認呼叫來自 Drime。

#新增 Webhook

1. 開啟設定 > 開發人員 > Webhook。

   您也可以從簽署中按一下偏好設定，開啟 Webhook 分頁，然後按一下開啟開發者設定。

2. 按一下新增 Webhook。

3. 在端點 URL 中，輸入接收呼叫的伺服器位址。

4. 在事件下方，將每個要接收的事件設為開啟，然後按一下建立 Webhook。

   畫面會顯示已建立 Webhook。

5. 請立即複製密鑰，然後按一下完成。

   Webhook 密鑰，請立即複製：密鑰只會顯示這一次。請將它存放在安全的地方。

#事件

#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 為例：

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 及其傳送記錄嗎？

#遇到問題時

#後續步驟

• 開發應用程式或串接 Webhook

• 建立 API 權杖

• 已簽署文件的稽核憑證包含哪些內容