Webhooks

透過 Webhook，您的應用程式可即時接收來自 PDFSimple 的事件通知。您無需輪詢 API 以查詢工作狀態，只需註冊一個端點，PDFSimple 便會在事件發生時，以 POST 方式將已簽署的內容傳送至該端點。

設定 Webhook

1. 前往「儀表板 → Webhooks」，點擊「新增端點」。
2. 輸入您的 HTTPS 端點網址（例如：https://yourapp.com/webhooks/pdfsimple）。
3. 選擇您想接收的事件（例如：job.completed、job.failed）。
4. 點擊「建立」。系統將顯示一組獨一無二的 Webhook 密鑰——請立即複製，此密鑰僅會顯示一次。
5. 請將此密鑰安全地儲存於您應用程式的環境變數中。

Webhook 事件

• job.completed——PDF 處理工作已成功完成。內容包含工作 ID、輸出檔案網址及中繼資料。
• job.failed——工作發生錯誤。內容包含錯誤訊息。

驗證 Webhook 簽章

每個 Webhook 請求都包含一個 X-PDFSimple-Signature 標頭，內含使用您的 Webhook 密鑰計算出的原始請求內容 HMAC-SHA256 簽章。請務必在處理內容前先驗證此簽章。

const crypto = require('crypto');

function verifySignature(rawBody, secret, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

重試機制與傳送保證

若您的端點未在 30 秒內回傳 2xx 回應，PDFSimple 將以指數退避方式重試傳送，於 30 天內最多重試 5 次。Webhook 事件將保留 30 天。