Webhooks

Was sind Webhooks?

Webhooks ermöglichen es Ihrer Anwendung, Echtzeitbenachrichtigungen über Ereignisse zu erhalten, die in Quote3D stattfinden. Anstatt die API auf Updates abzufragen (z. B. um zu prüfen, ob ein Angebot fertiggestellt wurde), sendet Quote3D eine HTTP POST-Anfrage an eine von Ihnen angegebene URL, sobald ein Ereignis eintritt.

Dies ist viel effizienter und ermöglicht es Ihnen, automatisierte Arbeitsabläufe in Ihrem eigenen System auszulösen, z. B. das Aktualisieren eines Bestellstatus, das Benachrichtigen eines Kunden oder das Starten eines Produktionsauftrags.

Verfügbare Ereignisse

• quote.completed: Wird ausgelöst, wenn eine 3D-Kostenschätzung erfolgreich abgeschlossen wurde.
• quote.failed: Wird ausgelöst, wenn eine Kostenschätzung aus irgendeinem Grund fehlschlägt.
• file.uploaded: Wird ausgelöst, wenn eine neue Modelldatei erfolgreich in Ihrem Konto hochgeladen wurde.
• file.deleted: Wird ausgelöst, wenn eine Modelldatei aus Ihrem Speicher gelöscht wurde.
• job.status_changed: Wird während verschiedener Phasen eines asynchronen Verarbeitungsprozesses ausgelöst.
• widget.added_to_cart: Ausgelöst, wenn ein Kunde ein Modell mit Ihrem einbettbaren Widget in seinen Warenkorb hinzufügt.

Beispiel-Nutzlast

Alle Webhook-Anfragen werden als JSON gesendet. Hier ist ein Beispiel für eine Nutzlast eines "quote.completed" Ereignisses:

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

Sicherheit & Verifizierung

Um sicherzustellen, dass Webhook-Anfragen tatsächlich von Quote3D stammen und nicht manipuliert wurden, fügen wir eine HMAC-SHA256-Signatur in den X-Webhook-Signature-Header und den Eventnamen in X-Webhook-Event hinzu.

Wenn Sie einen Webhook im Dashboard erstellen, wird Ihnen ein eindeutiger Secret Key angezeigt. Sie sollten diesen Schlüssel verwenden, um die Signatur jeder eingehenden Anfrage zu verifizieren.

Verifizierungsschritte:

1. Lesen Sie den rohen Anfragekörper als Zeichenkette.
2. Rufen Sie die Signatur aus dem X-Webhook-Signature-Header und den Ereignisnamen aus X-Webhook-Event ab.
3. Berechnen Sie den HMAC-SHA256-Hash des rohen Körpers mit Ihrem Webhook Secret.
4. Vergleichen Sie Ihren berechneten Digest mit dem SHA256-Präfix und der Signatur. Wenn sie übereinstimmen, ist die Anfrage authentisch.

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 verwalten

Sie können Ihre Webhooks direkt im Dashboard verwalten:

1. Gehen Sie in Ihrem Dashboard zur Seite 'Webhooks'.
2. Klicken Sie auf 'Neuen Webhook', um einen neuen Endpunkt hinzuzufügen.
3. Geben Sie Ihre Endpoint-URL (muss HTTPS sein) ein und wählen Sie die Ereignisse aus, für die Sie Benachrichtigungen erhalten möchten.
4. Kopieren Sie Ihren Secret Key sofort und speichern Sie ihn sicher. Sie können ihn danach nicht mehr einsehen!
5. Geben Sie optional einen API-Token-Link an, wenn der Webhook nur für Aktionen ausgelöst werden soll, die mit diesem spezifischen API-Token ausgeführt werden.

Wiederholung fehlgeschlagener Zustellungen

Wenn ein Webhook-Ziel vorübergehend nicht verfügbar war oder einen Fehler zurückgegeben hat, können Sie die Zustellung im Dashboard prüfen und für diesen spezifischen Zustellungsdatensatz eine erneute Zustellung auslösen.

Best Practices

• Senden Sie umgehend einen 200 OK-Status zurück, um den Empfang des Webhooks zu bestätigen.
• Führen Sie rechenintensive Prozesse asynchron aus (z. B. mit einer Hintergrundwarteschlange), um Timeouts zu vermeiden.
• Überprüfen Sie immer die Signatur, um Ihren Endpunkt vor unbefugten Anfragen zu schützen.
• Idempotenz: Stellen Sie sicher, dass Ihr System denselben Webhook mehrfach problemlos verarbeiten kann, da wir bei vorübergehenden Fehlern möglicherweise Wiederholungsversuche unternehmen.