Webhooks für Angebots- und Job-Ereignisse

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 bei jedem Zustandsübergang eines asynchronen Jobs ausgelöst (wartend, in Bearbeitung, abgeschlossen, fehlgeschlagen). Ein einzelnes Angebot erzeugt mehrere davon.
• widget.added_to_cart: Ausgelöst, wenn ein Kunde ein Modell mit Ihrem einbettbaren Widget in seinen Warenkorb hinzufügt.

Anforderungen an den Endpunkt

Ihre Endpunkt-URL wird beim Speichern validiert und erneut vor jedem Zustellversuch. URLs, die diese Regeln nicht erfüllen, werden mit einer 400er-Antwort abgelehnt.

• Muss http oder https verwenden. Andere Protokolle werden abgelehnt.
• Darf keine Anmeldedaten enthalten. https://user:[email protected] wird abgelehnt.
• Darf nicht auf eine private oder reservierte Adresse auflösen: localhost, Loopback, Link-Local (einschließlich Cloud-Instanz-Metadaten), private Bereiche, CGNAT, Multicast und reservierter Bereich.
• Der Hostname wird bei jedem Versuch via DNS aufgelöst, daher wird auch ein öffentlicher Hostname, der auf einen privaten Bereich verweist, abgelehnt.
• Weiterleitungen werden nicht befolgt. Geben Sie Ihre Antwort direkt über die registrierte URL zurück.

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 Endpunkt-URL ein und wählen Sie die Ereignisse aus, die Sie überwachen möchten. HTTPS wird dringend empfohlen; siehe oben die Anforderungen an den Endpunkt.
4. Kopieren Sie Ihren Secret Key sofort und speichern Sie ihn sicher. Sie können ihn danach nicht mehr einsehen!
5. Optional können Sie einen API-Token verknüpfen. Lassen Sie das Feld leer, und der Webhook wird bei jeder Anfrage auf Ihrem Konto ausgelöst; verknüpfen Sie einen Token, und er wird nur für Anfragen ausgelöst, die mit diesem Token getätigt werden.

Wiederholung fehlgeschlagener Zustellungen

Automatische Wiederholungsversuche

Eine fehlgeschlagene Zustellung wird automatisch wiederholt, bevor Sie eingreifen müssen. Es werden bis zu 3 Zustellversuche unternommen; danach wird die Zustellung als fehlgeschlagen abgeschlossen und bleibt im Dashboard sichtbar.

• Der erste Versuch erfolgt unmittelbar nach dem Auslösen des Events. Die restlichen Versuche werden durch einen Hintergrund-Sweep erfasst, sodass der tatsächliche zeitliche Abstand zwischen den Versuchen durch das Sweep-Intervall und nicht durch eine feste Anzahl von Sekunden bestimmt wird.
• Wird unser Prozess während eines Versuchs unterbrochen, wird die Zustellung zurückgefordert und erneut versucht, anstatt verloren zu gehen.
• Jede Zustellung wird vor dem Senden atomar beansprucht, sodass ein Wiederholungsversuch niemals dazu führt, dass dieselbe Zustellung zweimal gleichzeitig gesendet wird.
• Ein Wiederholungsversuch sendet exakt denselben Body und dieselbe X-Webhook-Signature wie der ursprüngliche Versuch, sodass Ihre bestehende Verifizierungslogik unverändert funktioniert.

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.