Webhooks

What are Webhooks?

Webhooks allow your application to receive real-time notifications about events happening in Quote3D. Instead of polling our API for updates (e.g., checking if a quote is finished), Quote3D will send an HTTP POST request to a URL you specify as soon as an event occurs.

This is much more efficient and allows you to trigger automated workflows in your own system, such as updating an order status, notifying a customer, or starting a production job.

Available Events

• quote.completed: Triggered when a 3D quote calculation is successfully finished.
• quote.failed: Triggered if a quote calculation fails for any reason.
• file.uploaded: Triggered when a new model file is successfully uploaded to your account.
• file.deleted: Triggered when a model file is deleted from your storage.
• job.status_changed: Triggered during various stages of an asynchronous processing job.
• widget.added_to_cart: Triggered when a customer adds a model to their cart using your embeddable widget.

Payload Example

All webhook requests are sent as JSON. Here is an example of a quote.completed event payload:

{
  "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
  }
}

Security & Verification

To ensure that webhook requests are genuinely from Quote3D and haven't been tampered with, we include an HMAC-SHA256 signature in the X-Webhook-Signature header and the event name in X-Webhook-Event.

When you create a webhook in the dashboard, you'll be shown a unique Secret Key. You should use this key to verify the signature of every incoming request.

Verification Steps:

1. Read the raw request body as a string.
2. Retrieve the signature from the X-Webhook-Signature header and the event name from X-Webhook-Event.
3. Compute the HMAC-SHA256 hash of the raw body using your Webhook Secret.
4. Prefix your calculated digest with sha256= and compare it with the signature. If they match, the request is authentic.

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);
}

Managing Webhooks

You can manage your webhooks directly from the Dashboard:

1. Go to the Webhooks page in your dashboard.
2. Click New Webhook to add a new endpoint.
3. Enter your Endpoint URL (must be HTTPS) and select the Events you want to listen for.
4. Copy your Secret Key immediately and store it securely. You won't be able to see it again!
5. Provide an optional API Token link if you want the webhook to only trigger for actions performed with that specific token.

Retrying Failed Deliveries

If a webhook destination was temporarily unavailable or returned an error, you can inspect the delivery in the dashboard and trigger a resend for that specific delivery record.

Best Practices

• Return a 200 OK status immediately to acknowledge receipt of the webhook.
• Perform heavy processing asynchronously (e.g., using a background task queue) to avoid timing out.
• Always verify the signature to protect your endpoint from unauthorized requests.
• Idempotency: Ensure your system can handle the same webhook multiple times gracefully, as we may retry deliveries in case of transient errors.