Webhooks

Quote3Dをリアルタイム通知でワークフローに統合します。

Webhookとは何ですか？

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

検証手順:

生の要求ボディを文字列として読み取ります。
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);
}

Webhook の管理

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

ダッシュボードの Webhook ページに移動します。
新しいエンドポイントを追加するには、新しい Webhook をクリックします。
エンドポイント URL (HTTPS である必要があります) を入力し、リッスンするイベントを選択します。
すぐにシークレットキーをコピーして安全な場所に保管してください。後で確認することはできません!
特定のAPIトークンでのみアクションが実行された場合にWebhookをトリガーしたい場合は、オプションのAPIトークンリンクを提供してください。

配信失敗の再試行

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

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

このエンドポイントは、既存のWebhook配信に対して新しい配信試行を作成します。受信サーバーを修正した後や、デバッグのために特定のイベントを再生したい場合に役立ちます。

Webhookの詳細ビューを使用して、再生したい配信IDを特定してください。
Webhook IDと配信IDの両方を使用して再送エンドポイントを呼び出します。APIは202 Acceptedで応答し、新しい保留中の配信レコードを作成します。
Webhookは依然としてアクティブであり、認証されたユーザーに属している必要があります。そうでない場合、再送リクエストは拒否されます。

ベストプラクティス

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