Hoe je Konfiwear-webhooks kunt integreren met je eigen winkelwagen (stap voor stap)

Wat je gaat doen

In deze tutorial koppel je Konfiwear aan elk platform dat je beheert — een OpenCart-winkel, een op maat gemaakte PHP-webshop, een headless storefront — met behulp van de Save/API-modus. Wanneer een klant klaar is met ontwerpen in de 3D-configurator en op de CTA-knop klikt, stuurt Konfiwear de volledige ontwerpgegevens naar je HTTPS-eindpunt: voorbeeldafbeeldingen, prijzen, maatoverzicht en verwijzingen naar productiebestanden. Vanaf daar neemt jouw code het over — voeg het artikel toe aan je winkelwagen, maak een bestelling aan, of wat je workflow ook vereist.

Als je Shopify of WooCommerce gebruikt, heb je dit allemaal niet nodig — maak in plaats daarvan gebruik van de ingebouwde winkelwagenintegraties. De Save/API-modus is bedoeld voor alle anderen.

Vereisten:

• Een Konfiwear-werkruimte met toegang tot de Save/API-modus
• Beheerdersrechten voor de instellingen van je werkruimte
• Een openbaar bereikbaar HTTPS-eindpunt dat POST-verzoeken kan ontvangen

Aan het einde heb je:

• De Save/API-modus ingeschakeld, waarbij je webhook-URL is geconfigureerd en getest
• Handtekeningverificatie die je eindpunt beschermt tegen vervalste verzoeken
• Je eigen sessiecontext die van je pagina via het iframe van de customizer terug naar je server stroomt

Stap 1 — Schakel de modus Opslaan/API in

1. Open in Konfiwear je teamwerkruimte.
2. Ga naar Instellingen → Algemeen → Oproep tot actie.
3. Selecteer onder Actiemodus de optie Opslaan / API.
4. Voer in het veld Webhook-URL je HTTPS-eindpunt in (bijvoorbeeld https://shop.example.com/konfiwear/webhook).
5. Klik op Test verzenden — Konfiwear verstuurt een voorbeeldpayload naar je eindpunt en toont je de HTTP-status en responstijd.
6. Klik op Wijzigingen opslaan.

Stap 2 — De payload begrijpen

Wanneer een klant een ontwerp indient, ontvangt je eindpunt een design.saved.v3-gebeurtenis:

{
  "event": "design.saved.v3",
  "transaction_id": "order-draft-8841",
  "session": {
    "id": "uuid",
    "passthrough": { "s": "your-echoed-value" }
  },
  "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 }
      }
    }
  ]
}

Hier is een echte levering die is geïnspecteerd in een webhook-debugger — let op de verzoekheaders X-Konfiwear-Event en X-Konfiwear-Signature naast de JSON-body:

• transaction_id — een referentie die je in de customizer-URL hebt geplaatst en die naar je wordt teruggestuurd (stap 4).
• session.passthrough — extra waarden die je hebt geconfigureerd om terug te sturen, eveneens afkomstig uit de URL (stap 4). Alleen aanwezig indien geconfigureerd.
• quote_id — het unieke ID van deze inzending. Gebruik dit om duplicaten te verwijderen.
• assets — voorbeeldafbeeldingen plus productiebestanden. Techpacks en drukbestanden worden op de achtergrond gegenereerd; ze komen eerst binnen als "pending", en een vervolggebeurtenis design.assets.ready wordt naar dezelfde URL verzonden zodra elk bestand gereed is.

Stap 3 — Handtekeningen verifiëren (aanbevolen)

Voordat je iets in de body van een webhook vertrouwt, moet je controleren of het verzoek daadwerkelijk afkomstig is van Konfiwear.

Genereer je geheim: klik in Instellingen → Algemeen → Call to Action → Webhook-ondertekening op Geheim genereren en kopieer het onmiddellijk — het wordt precies één keer weergegeven. Sla het op in een omgevingsvariabele, nooit in je code of repository. Als het ooit uitlekt, genereer het dan opnieuw en werk je omgeving bij.

$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); // veilig te verwerken

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

De meest voorkomende valkuil: controleer altijd aan de hand van de ruwe request body. Als je framework de JSON eerst parseert en je deze vervolgens weer omzet naar een string, zal de digest niet overeenkomen.

Stap 4 — De Customizer insluiten en je eigen context doorgeven

De meeste Save/API-integraties sluiten de customizer in via een iframe. De uitdaging: wanneer de webhook op je server binnenkomt, hoe weet je dan van welke van je klanten deze afkomstig is? Je kunt niet vertrouwen op je sessiecookie — browsers blokkeren cookies van derden binnen iframes. Geef in plaats daarvan je context door via de URL en laat Konfiwear deze terugsturen.

Voeg een referentie naar keuze toe aan de URL die je in het iframe laadt:

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

Konfiwear stuurt deze letterlijk terug in elke webhook voor die sessie. Genereer deze aan de serverzijde, sla hem op in de sessie van de klant, en je hebt een betrouwbare koppelsleutel.

Aangepaste parameters: sessie-doorgave

Als je platform al een sessietoken genereert onder een eigen parameternaam (bijvoorbeeld s):

1. Voeg in Instellingen → Algemeen → Call to Action de parameternaam toe aan Parameters voor sessie-doorgave.
2. Voeg deze toe aan de URL van je iframe: ...?s=7a6f2ca2f15d3a691aaac9ecbc
3. Lees deze terug uit de webhook via session.passthrough.s.

Alleen parameternamen die op je geconfigureerde toelatingslijst staan, worden doorgegeven — al het andere in de URL wordt genegeerd. De namen design, quote, rev, saved en transaction_id zijn gereserveerd.

Konfiwear stuurt ook een browserbericht naar je bovenliggende pagina wanneer een verzending slaagt (konfiwear:design.saved), zodat je frontend direct kan reageren — een bevestiging tonen, doorverwijzen naar het winkelwagentje — zonder je server te pollen.

Stap 5 — Ga veilig om met de webhook

De standaardregels voor webhooks gelden voor Konfiwear op dezelfde manier als voor Stripe of Shopify:

1. Controleer eerst de handtekening. Je webhook-URL is bereikbaar via het openbare internet; de handtekening is het slot. Wijs alles af wat niet klopt.
2. Behandel teruggestuurde waarden als opzoeksleutels, niet als authenticatie. transaction_id en session.passthrough zijn afkomstig van een URL in de browser van een klant. Gebruik ze om de bijbehorende sessie in je eigen winkel te vinden en controleer of die sessie door jou is aangemaakt en nog steeds actief is — voordat je iets aan een actief winkelmandje toevoegt.
3. Controleer de prijzen opnieuw aan de hand van je eigen catalogus voordat je iemand iets in rekening brengt, net zoals je inkomende bestelgegevens nogmaals zou controleren voordat deze in het betalingsproces terechtkomen.
4. Verwijder duplicaten op basis van quote_id, zodat een herhaalde levering geen dubbele bestelling oplevert.
5. Bevestig snel, verwerk asynchroon. Je hebt 10 seconden om een 2xx-status te retourneren — sla de payload op, stuur een 200-antwoord en voer de zware taken (downloads, wijzigingen in het winkelmandje, ERP-aanroepen) uit in een achtergrondtaak.

Alles bij elkaar ziet een robuuste handler er als volgt uit:

POST ontvangen
  → handtekening van de ruwe body verifiëren          (afwijzen indien ongeldig)
  → duplicaten verwijderen op basis van `quote_id`                      (200 retourneren indien al gezien)
  → passthrough-token opzoeken in eigen winkel  (negeren indien onbekend)
  → payload opslaan, achtergrondtaak in de wachtrij plaatsen
  → 200 retourneren
achtergrondtaak
  → prijs opnieuw valideren aan de hand van eigen catalogus
  → artikel aan winkelwagen toevoegen / bestelling aanmaken

Probleemoplossing

Klaar om te bouwen?

De Save/API-modus verandert Konfiwear in een ontwerp-frontend voor welke e-commerce-stack je ook gebruikt. Schakel deze modus in via Instellingen → Algemeen → Call to Action, stel de handtekeningverificatie in, en je platform ontvangt elk geconfigureerd ontwerp met bijgevoegde prijzen, voorbeelden en productiebestanden.

Start je gratis proefperiode en koppel Konfiwear vandaag nog aan je platform.