Webhook

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 durante le diverse fasi di un job di elaborazione asincrono.
• widget.added_to_cart: Attivato quando un cliente aggiunge un modello al carrello utilizzando il widget incorporabile.

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 dell'Endpoint (deve essere HTTPS) e seleziona gli Eventi che vuoi intercettare.
4. Copia immediatamente la tua Chiave Segreta e conservala in un luogo sicuro. Non potrai visualizzarla di nuovo!
5. Fornisci un link opzionale a un Token API se vuoi che il webhook si attivi solo per le azioni eseguite con quel token specifico.

Riprovare le Consegne Fallite

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.