Come integrare i webhook di Konfiwear con il tuo carrello personalizzato (passo dopo passo)

Cosa otterrai

In questo tutorial collegherai Konfiwear a qualsiasi piattaforma di cui disponi — un negozio OpenCart, un negozio PHP personalizzato, un front-end headless — utilizzando la modalità Salva/API. Quando un cliente termina di personalizzare il prodotto nel configuratore 3D e clicca sul pulsante CTA, Konfiwear invia il payload completo del progetto al tuo endpoint HTTPS: immagini di anteprima, prezzi, ripartizione delle taglie e riferimenti ai file di produzione. Da lì, subentra il tuo codice: aggiungi l’articolo al carrello, crea un ordine o esegui qualsiasi altra operazione richiesta dal tuo flusso di lavoro.

Se utilizzi Shopify o WooCommerce, non hai bisogno di nulla di tutto ciò: usa invece le integrazioni native con il carrello. La modalità Salva/API è destinata a tutti gli altri.

Requisiti:

• Uno spazio di lavoro Konfiwear con accesso alla modalità Salva/API
• Accesso amministrativo alle impostazioni del tuo spazio di lavoro
• Un endpoint HTTPS accessibile pubblicamente in grado di ricevere richieste POST

Al termine, avrai:

• La modalità Save/API abilitata con il tuo URL del webhook configurato e testato
• La verifica della firma che protegge il tuo endpoint da richieste contraffatte
• Il tuo contesto di sessione che fluisce dalla tua pagina, attraverso l’iframe del customizer, e torna al tuo server

Passaggio 1 — Abilita la modalità Salva/API

1. In Konfiwear, apri il tuo spazio di lavoro del team.
2. Vai su Impostazioni → Globali → Call to Action.
3. Sotto Modalità azione, seleziona Salva / API.
4. Nel campo URL webhook, inserisci il tuo endpoint HTTPS (ad esempio, https://shop.example.com/konfiwear/webhook).
5. Fai clic su Invia test: Konfiwear invia un payload di prova al tuo endpoint e ti mostra lo stato HTTP e il tempo di risposta.
6. Fai clic su Salva modifiche.

Passaggio 2 — Comprendere il payload

Quando un acquirente invia un progetto, il tuo endpoint riceve un evento design.saved.v3:

{
  "event": "design.saved.v3",
  "transaction_id": "order-draft-8841",
  "session": {
    "id": "uuid",
    "passthrough": { "s": "il-tuo-valore-ripetuto" }
  },
  "products": [
    {
      "product": { "code": "jersey", "name": "Jersey" },
      "quote": { "quote_id": "uuid", "quote_number": "QR-1001" },
      "design": { "size_breakdown": { "m": 2, "l": 1 } },
      "pricing": { "unit_price": 42,63, "total": 127,89, "currency": "EUR" },
      "assets": {
        "previews": [{ "status": "ready", "url": "https://..." }],
        "techpack": { "status": "pending", "url": null }
      }
    }
  ]
}

Ecco una consegna reale esaminata in un debugger per webhook — si notino le intestazioni di richiesta X-Konfiwear-Event e X-Konfiwear-Signature accanto al corpo JSON:

• transaction_id — un riferimento che inserisci nell’URL del configuratore e che ti viene restituito (Passaggio 4).
• session.passthrough — valori aggiuntivi che hai configurato per la restituzione, anch’essi provenienti dall’URL (Passaggio 4). Presente solo se configurato.
• quote_id — l’ID univoco di questo invio. Utilizzarlo per eliminare i duplicati.
• assets — immagini di anteprima e file di produzione. I techpack e i file di stampa vengono generati in background; inizialmente vengono contrassegnati come "pending", e un evento successivo design.assets.ready viene inviato allo stesso URL quando ogni file è pronto.

Passaggio 3 — Verifica delle firme (consigliato)

Prima di fidarti di qualsiasi cosa contenuta nel corpo di un webhook, verifica che la richiesta provenga effettivamente da Konfiwear.

Genera il tuo segreto: in Impostazioni → Globali → Call to Action → Firma webhook, clicca su Genera segreto e copialo immediatamente — viene visualizzato una sola volta. Salvalo in una variabile d’ambiente, mai nel tuo codice o nel repository. Se dovesse mai trapelare, rigeneralo e aggiorna il tuo ambiente.

$rawBody = file_get_contents('php://input');
$secret  = getenv('KONFIWEAR_WEBHOOK_SECRET');

$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$provided = $_SERVER['HTTP_X_KONFIWEAR_SIGNATURE'] ?? '';

if (!hash_equals($expected, $provided)) {
    http_response_code(401);
    exit;
}

$payload = json_decode($rawBody, true); // sicuro da elaborare

import { createHmac, timingSafeEqual } from 'node:crypto';

function isValidSignature(rawBody, header, secret) {
  const expected =
    'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');

  return (
    header?.length === expected.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(header))
  );
}

L'errore più comune: verificare sempre il corpo della richiesta non elaborato. Se il tuo framework analizza prima il JSON e poi lo riconverti in stringa, il digest non corrisponderà.

Passaggio 4 — Incorpora il Customizer e passa il tuo contesto

La maggior parte delle integrazioni Save/API incorpora il Customizer in un iframe. La sfida: quando il webhook arriva al tuo server, come fai a sapere a quale dei tuoi acquirenti appartiene? Non puoi fare affidamento sul cookie di sessione: i browser bloccano i cookie di terze parti all’interno degli iframe. Passa invece il tuo contesto tramite l’URL e lascia che Konfiwear lo restituisca.

Aggiungi un riferimento a tua scelta all’URL che carichi nell’iframe:

https://your-domain/c/your-team/jersey?transaction_id=order-draft-8841

Konfiwear lo ripropone alla lettera in ogni webhook relativo a quella sessione. Generalo lato server, memorizzalo associandolo alla sessione dell’acquirente e avrai una chiave di join affidabile.

Parametri personalizzati: passaggio della sessione

Se la tua piattaforma genera già un token di sessione con un proprio nome di parametro (ad esempio, s):

1. In Impostazioni → Globali → Call to Action, aggiungi il nome del parametro a Parametri di passaggio della sessione.
2. Aggiungetelo all’URL del vostro iframe: ...?s=7a6f2ca2f15d3a691aaac9ecbc
3. Recuperatelo dal webhook all’indirizzo session.passthrough.s.

Vengono restituiti solo i nomi dei parametri presenti nella lista di autorizzazione configurata; qualsiasi altro elemento presente nell’URL viene ignorato. I nomi design, quote, rev, saved e transaction_id sono riservati.

Konfiwear invia inoltre un messaggio del browser alla tua pagina principale quando l’invio va a buon fine (konfiwear:design.saved), così il tuo frontend può reagire istantaneamente — mostrare una conferma, reindirizzare al carrello — senza dover interrogare il tuo server.

Passaggio 5 — Gestisci il webhook in modo sicuro

Le norme standard di sicurezza relative ai webhook si applicano a Konfiwear allo stesso modo in cui si applicano a Stripe o Shopify:

1. Verifica innanzitutto la firma. L’URL del tuo webhook è raggiungibile dalla rete Internet pubblica; la firma funge da lucchetto. Rifiuta qualsiasi richiesta non valida.
2. Considera i valori restituiti come chiavi di ricerca, non come autenticazione. transaction_id e session.passthrough provengono da un URL nel browser dell’acquirente. Utilizzali per individuare la sessione corrispondente nel tuo negozio e verifica che si tratti di una sessione da te generata e ancora attiva, prima di aggiungere qualsiasi articolo a un carrello attivo.
3. Convalida nuovamente i prezzi rispetto al tuo catalogo prima di addebitare qualsiasi importo, proprio come ricontrolleresti i dati di qualsiasi ordine in entrata prima che entri nel flusso di pagamento.
4. Elimina i duplicati in base a quote_id in modo che un tentativo di consegna ripetuto non crei un doppio ordine.
5. Rispondi rapidamente, elabora in modo asincrono. Hai 10 secondi per restituire un codice di stato 2xx: salva il payload, rispondi con 200 ed esegui le operazioni più impegnative (download, modifiche al carrello, chiamate all’ERP) in un processo in background.

Nel complesso, un gestore affidabile si presenta così:

ricevi POST
  → verifica la firma sul corpo grezzo          (rifiuta se non valida)
  → elimina i duplicati in base a `quote_id`                      (restituisci 200 se già visto)
  → cerca il token di passthrough nel proprio negozio  (ignora se sconosciuto)
  → salvare il payload, accodare il processo in background
  → restituire 200
processo in background
  → rivalidare il prezzo rispetto al proprio catalogo
  → aggiungere l’articolo al carrello / creare l’ordine

Risoluzione dei problemi

Pronto a creare?

La modalità Save/API trasforma Konfiwear in un front-end di progettazione per qualsiasi stack e-commerce tu utilizzi. Abilitala in Impostazioni → Globali → Call to Action, configura la verifica della firma e la tua piattaforma riceverà ogni design configurato con prezzi, anteprime e file di produzione allegati.

Inizia la tua prova gratuita e collega Konfiwear alla tua piattaforma oggi stesso.