Webhook

Webhook 使您的应用程序能够接收来自 PDFSimple 的实时事件通知。无需轮询 API 查询任务状态，只需注册一个端点，PDFSimple 会在事件发生时向其发送带签名的负载（POST 请求）。

设置 webhook

1. 前往仪表盘 → Webhook，点击“添加端点”。
2. 输入您的 HTTPS 端点 URL（例如 https://yourapp.com/webhooks/pdfsimple）。
3. 选择您想接收的事件（例如 job.completed、job.failed）。
4. 点击“创建”。系统会显示一个唯一的 webhook 密钥——请立即复制，它只会显示一次。
5. 将该密钥安全地存储在应用程序的环境变量中。

Webhook 事件

• job.completed —— PDF 处理任务成功完成。负载中包含任务 ID、输出文件 URL 及元数据。
• job.failed —— 任务遇到错误。负载中包含错误信息。

验证 webhook 签名

每个 webhook 请求都包含一个 X-PDFSimple-Signature 请求头，其中含有基于原始请求体计算得出的 HMAC-SHA256 签名，该签名使用您的 webhook 密钥计算生成。在处理负载之前，请务必先验证此签名。

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 天。