見積もりとジョブのイベント用 Webhook

Webhook とは何ですか ?

Webhook を使用すると、Quote3D で発生したイベントに関するリアルタイム通知をアプリケーションで受信できます。API をポーリングして更新状況を確認する代わりに (たとえば、見積もりが完了したかどうかを確認するなど)、Quote3D はイベントが発生するとすぐに、指定した URL に HTTP POST リクエストを送信します。

これははるかに効率的であり、注文状況の更新、顧客への通知、または生産ジョブの開始など、独自のシステムで自動ワークフローをトリガーできます。

利用可能なイベント

• quote.completed: 3D 見積もり計算が正常に完了したときにトリガーされます。
• quote.failed: 何らかの理由で、見積もり計算が失敗した場合にトリガーされます。
• file.uploaded: 新しいモデルファイルがアカウントに正常にアップロードされたときにトリガーされます。
• file.deleted: モデルファイルがストレージから削除されたときにトリガーされます。
• job.status_changed: 非同期ジョブの状態遷移ごと (queued、processing、completed、failed) に発火します。1件の見積もりで複数回発生します。
• widget.added_to_cart: 顧客が埋め込みウィジェットを使用してモデルをカートに追加したときにトリガーされます。
• usage.alert: アカウントの見積もり枠またはストレージ枠が80% または100% を超えたとき、および使用量が80% を下回ったとき (level 0) に送信されます。

エンドポイントの要件

エンドポイント URL は保存時と、配信を試行するたびに検証されます。これらのルールを満たさない URL は400レスポンスで拒否されます。

• http または https を使用する必要があります。それ以外のスキームは拒否されます。
• 認証情報を埋め込んではいけません。https://user:[email protected] は拒否されます。
• プライベートまたは予約済みアドレスに解決してはいけません: localhost、ループバック、リンクローカル (クラウドインスタンスメタデータを含む)、プライベート範囲、CGNAT、マルチキャスト、予約領域。
• ホスト名は試行のたびに DNS で解決されるため、プライベート領域を指す公開ホスト名も拒否されます。
• リダイレクトは追跡されません。登録した URL から直接レスポンスを返してください。

ペイロードの例

すべての 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,
    "cached": false,
    "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 を作成すると、一意のシークレットキーが表示されます。受信するすべてのリクエストの署名を検証するために、このキーを使用する必要があります。

検証手順:

1. 生の要求ボディを文字列として読み取ります。
2. X-Webhook-Signature ヘッダーから署名と X-Webhook-Event からイベント名を取得します。
3. Webhook シークレットを使用して、生のボディの HMAC-SHA256ハッシュを計算します。
4. 計算されたダイジェストの前に 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);
}

Webhook の管理

Webhook はダッシュボードから直接管理できます:

1. ダッシュボードの Webhook ページに移動します。
2. 新しいエンドポイントを追加するには、新しい Webhook をクリックします。
3. エンドポイント URL を入力し、受信したいイベントを選択してください。HTTPS を強く推奨します。上記のエンドポイント要件をご覧ください。
4. すぐにシークレットキーをコピーして安全な場所に保管してください。後で確認することはできません !
5. 任意で API トークンを紐付けます。空のままにするとアカウント上のすべてのリクエストで Webhook が発火し、トークンを紐付けるとそのトークンで行われたリクエストのみで発火します。

配信失敗の再試行

自動再試行

失敗した配信は、お客様が対応する前に自動で再試行されます。配信は最大3回まで試行され、その後は失敗として終了し、ダッシュボードに残り続けます。

• 最初の試行はイベント発火と同時に行われます。残りの試行はバックグラウンドの巡回処理が拾うため、試行間隔は固定の秒数ではなく、その巡回間隔によって決まります。
• 処理が試行の途中で中断された場合、配信は失われるのではなく回収されて再試行されます。
• 各配信は送信前にアトミックに確保されるため、再試行によって同じ配信が同時に二重送信されることはありません。
• 再試行は元の試行とまったく同じボディと同じ X-Webhook-Signature を送信するので、既存の検証ロジックはそのまま機能します。

Webhook の送信先が一時的に利用できない状態であったり、エラーを返した場合、ダッシュボードで配信内容を確認し、その特定の配信レコードに対して再送をトリガーできます。

ベストプラクティス

• Webhook の受信を通知するために、直ちに200 OK ステータスを返してください。
• 時間切れを避けるため、重い処理は非同期的に実行してください (例: バックグラウンドタスクキューを使用)。
• 常に署名を検証して、不正なリクエストからエンドポイントを保護してください。
• べき等性: 一時的なエラーが発生した場合に再試行する可能性があるため、システムが同じ Webhook を複数回正常に処理できるようにしてください。