Webhooks

通过实时通知将 Quote3D 集成到您的工作流程中。

什么是 Webhooks？

Webhooks 允许您的应用程序接收有关 Quote3D 中发生的事件的实时通知。您无需轮询我们的 API 以获取更新（例如，检查报价是否完成），Quote3D 会在事件发生后立即向您指定的 URL 发送 HTTP POST 请求。

这效率更高，并允许您在自己的系统中触发自动化工作流程，例如更新订单状态、通知客户或启动生产作业。

可用事件

quote.completed: 当3D报价计算成功完成时触发。
quote.failed: 如果报价计算因任何原因失败时触发。
file.uploaded: 当新的模型文件成功上传到您的帐户时触发。
file.deleted: 当模型文件从您的存储空间中删除时触发。
job.status_changed: 在异步处理作业的各个阶段触发。
widget.added_to_cart: 当客户使用您的嵌入式小部件将模型添加到购物车时触发。

有效载荷示例

所有Webhook请求都以JSON格式发送。以下是一个quote.completed事件有效载荷的示例：

{
  "event": "quote.completed",
  "timestamp": "2026-03-10T14:30:00.000Z",
  "data": {
    "jobId": "job_01HXYZ123456789",
    "quoteId": "job_01HXYZ123456789",
    "status": "completed",
    "fileName": "gearbox-housing.stl",
    "fileId": "fl_987654321",
    "processingTimeMs": 22134,
    "result": {
      "quote_id": "job_01HXYZ123456789",
      "total_price": 25.5,
      "currency": "USD",
      "estimated_time": "2h 15m",
      "estimated_time_seconds": 8100,
      "filament_weight": 42.8,
      "printInfo": {
        "technology": "FDM",
        "material": "PLA",
        "color": "Black"
      }
    },
    "error": null
  }
}

安全与验证

为了确保 webhook 请求确实来自 Quote3D 且未被篡改，我们在 X-Webhook-Signature 标头中包含一个 HMAC-SHA256 签名。

当您在仪表板中创建 webhook 时，将显示一个唯一的 Secret Key。您应该使用此密钥来验证每个传入请求的签名。

验证步骤：

将原始请求体读取为字符串。
从 X-Webhook-Signature 标头中检索签名，并从 X-Webhook-Event 中检索事件名称。
使用您的 Webhook 密钥计算原始体的 HMAC-SHA256 哈希值。
将您计算出的摘要以 sha256= 为前缀，并将其与签名进行比较。如果它们匹配，则请求是真实的。

const crypto = require('crypto');

// Secret Key from your Quote3D Dashboard
const SECRET = 'your_webhook_secret_here';

function verifySignature(req) {
  const signature = req.headers['x-webhook-signature'];
  const event = req.headers['x-webhook-event'];
  const body = req.rawBody; // Keep the exact raw JSON string

  const hmac = crypto.createHmac('sha256', SECRET);
  const digest = 'sha256=' + hmac.update(body).digest('hex');

  if (typeof signature !== 'string' || typeof event !== 'string') {
    return false;
  }

  const received = Buffer.from(signature, 'utf8');
  const expected = Buffer.from(digest, 'utf8');

  return received.length === expected.length &&
    crypto.timingSafeEqual(received, expected);
}

管理 Webhooks

您可以直接从仪表盘管理您的 Webhooks:

前往仪表盘中的 Webhooks 页面。
点击“新建 Webhook”以添加新的端点。
输入您的端点 URL（必须是 HTTPS）并选择您想要监听的事件。
立即复制您的密钥并安全地存储它。您将无法再次查看它！
如果您希望 Webhook 仅对使用特定 API Token 执行的操作触发，请提供可选的 API Token 链接。

重试失败的投递

如果 webhook 目标地址暂时不可用或返回错误，您可以在仪表板中检查投递并为该特定投递记录触发重发。

`POST /v2/webhooks/{webhook_id}/deliveries/{delivery_id}/resend`

此端点为现有的 webhook 投递创建新的投递尝试。在您修复了接收服务器或希望为了调试重放特定事件后，它会很有用。

使用 webhook 详情视图来识别您想要重放的投递 ID。
使用 webhook ID 和 delivery ID 调用重发端点。API 将返回 202 Accepted 并创建一个新的待处理投递记录。
webhook 必须仍然处于活动状态并属于经过身份验证的用户，否则重发请求将被拒绝。

最佳实践

立即返回 200 OK 状态以确认已收到 webhook。
异步执行繁重处理（例如，使用后台任务队列）以避免超时。
始终验证签名以保护您的端点免受未经授权的请求。
幂等性：确保您的系统可以优雅地处理相同的 webhook 多次，因为我们可能会在瞬时错误的情况下重试交付。