Webhook per eventi di preventivo e lavoro

Cosa sono i Webhook?

I Webhook consentono alla tua applicazione di ricevere notifiche in tempo reale sugli eventi che si verificano in Quote3D. Invece di interrogare la nostra API per gli aggiornamenti (ad esempio, per verificare se un preventivo è completato), Quote3D invierà una richiesta HTTP POST a un URL che specifichi non appena si verifica un evento.

Questo è molto più efficiente e ti permette di attivare flussi di lavoro automatizzati nel tuo sistema, come l'aggiornamento dello stato di un ordine, la notifica a un cliente o l'avvio di un lavoro di produzione.

Eventi Disponibili

• quote.completed: Attivato quando il calcolo di un preventivo per la stampa 3D viene completato con successo.
• quote.failed: Attivato se il calcolo di un preventivo fallisce per qualsiasi motivo.
• file.uploaded: Attivato quando un nuovo file modello viene caricato correttamente sul tuo account.
• file.deleted: Attivato quando un file modello viene eliminato dal tuo spazio di archiviazione.
• job.status_changed: attivato a ogni transizione di stato di un lavoro asincrono (queued, processing, completed, failed). Un singolo preventivo ne produce diversi.
• widget.added_to_cart: Attivato quando un cliente aggiunge un modello al carrello utilizzando il widget incorporabile.

Requisiti dell'endpoint

L'URL del tuo endpoint viene convalidato al salvataggio e di nuovo prima di ogni tentativo di consegna. Gli URL che non superano queste regole vengono respinti con una risposta 400.

• Deve usare http o https. Gli altri schemi vengono respinti.
• Non deve contenere credenziali. https://user:[email protected] viene respinto.
• Non deve risolvere a un indirizzo privato o riservato: localhost, loopback, link-local (inclusi i metadati delle istanze cloud), intervalli privati, CGNAT, multicast e spazio riservato.
• Il nome host viene risolto via DNS a ogni tentativo, quindi anche un nome host pubblico che punta a uno spazio privato viene respinto.
• I reindirizzamenti non vengono seguiti. Restituisci la risposta direttamente dall'URL che hai registrato.

Esempio di Payload

Tutte le richieste webhook vengono inviate come JSON. Ecco un esempio di payload per l'evento 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
  }
}

Sicurezza e Verifica

Per garantire che le richieste webhook provengano autenticamente da Quote3D e non siano state manomesse, includiamo una firma HMAC-SHA256 nell'header X-Webhook-Signature.

Quando crei un webhook nella dashboard, ti verrà mostrata una Secret Key univoca. Dovresti utilizzare questa chiave per verificare la firma di ogni richiesta in arrivo.

Passaggi di Verifica:

1. Leggi il corpo della richiesta grezza come una stringa.
2. Recupera la firma dall'header X-Webhook-Signature e il nome dell'evento da X-Webhook-Event.
3. Calcola l'hash HMAC-SHA256 del corpo grezzo utilizzando la tua Secret Key Webhook.
4. Prefissa il digest calcolato con sha256= e confrontalo con la firma. Se corrispondono, la richiesta è autentica.

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

Gestione dei Webhook

Puoi gestire i tuoi webhook direttamente dalla Dashboard:

1. Vai alla pagina Webhooks nella tua dashboard.
2. Clicca su Nuovo Webhook per aggiungere un nuovo endpoint.
3. Inserisci l'URL del tuo endpoint e seleziona gli eventi da ascoltare. HTTPS è vivamente consigliato; vedi i Requisiti dell'endpoint sopra.
4. Copia immediatamente la tua Chiave Segreta e conservala in un luogo sicuro. Non potrai visualizzarla di nuovo!
5. Facoltativamente collega un token API. Lasciandolo vuoto, il webhook si attiva per ogni richiesta del tuo account; collegando un token, si attiva solo per le richieste fatte con quel token.

Riprovare le Consegne Fallite

Tentativi automatici

Una consegna fallita viene ritentata automaticamente prima ancora che tu debba intervenire. Le consegne vengono tentate fino a 3 volte; dopodiché la consegna viene chiusa come fallita e resta visibile nel pannello.

• Il primo tentativo avviene appena l'evento si attiva. I tentativi restanti vengono presi in carico da una scansione in background, quindi l'intervallo pratico tra i tentativi dipende da quella scansione e non da un numero fisso di secondi.
• Se il nostro processo si interrompe durante un tentativo, la consegna viene recuperata e ritentata anziché andare persa.
• Ogni consegna viene assegnata in modo atomico prima dell'invio, quindi un nuovo tentativo non porta mai a inviare due volte la stessa consegna in parallelo.
• Un nuovo tentativo invia esattamente lo stesso corpo e la stessa X-Webhook-Signature del tentativo originale, così la tua logica di verifica funziona senza modifiche.

Se una destinazione webhook era temporaneamente non disponibile o ha restituito un errore, è possibile ispezionare la consegna nella dashboard e attivare un nuovo invio per quella specifica registrazione di consegna.

Migliori Pratiche

• Restituisci immediatamente uno status 200 OK per confermare la ricezione del webhook.
• Esegui l'elaborazione pesante in modo asincrono (ad esempio, utilizzando una coda di attività in background) per evitare timeout.
• Verifica sempre la firma per proteggere il tuo endpoint da richieste non autorizzate.
• Idempotenza: Assicurati che il tuo sistema possa gestire lo stesso webhook più volte senza problemi, poiché potremmo riprovare le consegne in caso di errori transitori.