Comment intégrer les webhooks Konfiwear à votre panier personnalisé (étape par étape)

Ce que vous allez réaliser

Dans ce tutoriel, vous allez connecter Konfiwear à n'importe quelle plateforme que vous gérez — une boutique OpenCart, une boutique PHP personnalisée, une vitrine « headless » — en utilisant le mode Enregistrer/API. Lorsqu’un client a terminé de personnaliser son produit dans le configurateur 3D et clique sur le bouton d’appel à l’action, Konfiwear envoie l’ensemble des données de personnalisation à votre point de terminaison HTTPS : images d’aperçu, prix, répartition des tailles et références des fichiers de production. À partir de là, votre code prend le relais : ajoutez l’article à votre panier, créez une commande, ou effectuez toute autre action requise par votre processus.

Si vous utilisez Shopify ou WooCommerce, vous n’avez pas besoin de tout cela — utilisez plutôt les intégrations natives au panier. Le mode « Save/API » est destiné à tous les autres.

Prérequis :

• Un espace de travail Konfiwear avec accès au mode Save/API
• Un accès administrateur aux paramètres de votre espace de travail
• Un point de terminaison HTTPS accessible au public et capable de recevoir des requêtes POST

À la fin, vous aurez :

• Le mode Save/API activé, avec votre URL de webhook configurée et testée
• Une vérification de signature protégeant votre point de terminaison contre les requêtes falsifiées
• Votre propre contexte de session circulant depuis votre page, via l’iframe du personnalisateur, jusqu’à votre serveur

Étape 1 — Activer le mode Enregistrement/API

1. Dans Konfiwear, ouvrez votre espace de travail d’équipe.
2. Accédez à Paramètres → Globaux → Appel à l’action.
3. Sous Mode d’action, sélectionnez Enregistrement / API.
4. Dans le champ URL du webhook, saisissez votre point de terminaison HTTPS (par exemple, https://shop.example.com/konfiwear/webhook).
5. Cliquez sur Envoyer un test — Konfiwear envoie un exemple de charge utile à votre point de terminaison et vous indique le statut HTTP ainsi que le temps de réponse.
6. Cliquez sur Enregistrer les modifications.

Étape 2 — Comprendre la charge utile

Lorsqu’un client soumet un design, votre point de terminaison reçoit un événement design.saved.v3 :

{
  "event": "design.saved.v3",
  "transaction_id": "order-draft-8841",
  "session": {
    "id": "uuid",
    "passthrough": { "s": "votre-valeur-renvoyée" }
  },
  "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" },
      "ressources" : {
        "aperçus" : [{ "statut" : "prêt", "url" : "https://..." }],
        "fiche_technique" : { "statut" : "en attente", "url" : null }
      }
    }
  ]
}

Voici une livraison réelle inspectée dans un débogueur de webhooks — notez les en-têtes de requête X-Konfiwear-Event et X-Konfiwear-Signature à côté du corps JSON :

• transaction_id — une référence que vous avez ajoutée à l’URL du personnalisateur et qui vous est renvoyée (Étape 4).
• session.passthrough — des valeurs supplémentaires que vous avez configurées pour être renvoyées, également issues de l’URL (étape 4). Présent uniquement s’il a été configuré.
• quote_id — l’identifiant unique de cette soumission. Utilisez-le pour éliminer les doublons.
• assets — images d’aperçu et fichiers de production. Les dossiers techniques et les fichiers d’impression sont générés en arrière-plan ; ils apparaissent d’abord comme « en attente », puis un événement de suivi design.assets.ready est envoyé à la même URL lorsque chaque fichier est prêt.

Étape 3 — Vérifier les signatures (recommandé)

Avant de vous fier au contenu d’un corps de webhook, assurez-vous que la requête provient bien de Konfiwear.

Générez votre clé secrète : dans Paramètres → Global → Appel à l’action → Signature des webhooks, cliquez sur Générer la clé secrète et copiez-la immédiatement — elle n’apparaît qu’une seule fois. Enregistrez-le dans une variable d’environnement, jamais dans votre code ni dans votre dépôt. S’il venait à être divulgué, régénérez-le et mettez à jour votre environnement.

$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); // traitement sans risque

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'erreur courante à éviter : vérifiez toujours par rapport au corps brut de la requête. Si votre framework analyse d’abord le JSON et que vous le reconvertissez en chaîne de caractères, le digest ne correspondra pas.

Étape 4 — Intégrez le Customizer et transmettez votre propre contexte

La plupart des intégrations Save/API intègrent le Customizer dans un iframe. Le défi : lorsque le webhook arrive sur votre serveur, comment savoir à quel client il correspond ? Vous ne pouvez pas vous fier à votre cookie de session — les navigateurs bloquent les cookies tiers à l’intérieur des iframes. Transmettez plutôt votre contexte via l’URL et laissez Konfiwear le renvoyer.

Ajoutez une référence de votre choix à l’URL que vous chargez dans l’iframe :

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

Konfiwear la renvoie telle quelle dans chaque webhook de cette session. Générez-la côté serveur, stockez-la en association avec la session de l’acheteur, et vous disposez d’une clé de jointure fiable.

Paramètres personnalisés : transmission de session

Si votre plateforme génère déjà un jeton de session sous son propre nom de paramètre (par exemple, s) :

1. Dans Paramètres → Globaux → Appel à l’action, ajoutez le nom du paramètre à Paramètres de transmission de session.
2. Ajoutez-le à l’URL de votre iframe : ...?s=7a6f2ca2f15d3a691aaac9ecbc
3. Récupérez-le dans le webhook à l’adresse session.passthrough.s.

Seuls les noms de paramètres figurant sur votre liste blanche configurée sont renvoyés — tout autre élément présent dans l’URL est ignoré. Les noms design, quote, rev, saved et transaction_id sont réservés.

Konfiwear envoie également un message au navigateur sur votre page parente lorsqu’une soumission aboutit (konfiwear:design.saved), ce qui permet à votre interface utilisateur de réagir instantanément — afficher une confirmation, rediriger vers le panier — sans interroger votre serveur.

Étape 5 — Gérer le webhook en toute sécurité

Les règles standard de sécurité relatives aux webhooks s’appliquent à Konfiwear de la même manière qu’à Stripe ou Shopify :

1. Vérifiez d’abord la signature. L’URL de votre webhook est accessible depuis l’Internet public ; la signature est le verrou. Rejetez tout ce qui échoue à la vérification.
2. Considérez les valeurs renvoyées comme des clés de recherche, et non comme des éléments d’authentification. transaction_id et session.passthrough proviennent d’une URL dans le navigateur d’un client. Utilisez-les pour trouver la session correspondante dans votre propre boutique, et vérifiez que cette session est bien celle que vous avez émise et qu’elle est toujours active — avant d’ajouter quoi que ce soit à un panier en cours.
3. Revérifiez les prix par rapport à votre propre catalogue avant de facturer quoi que ce soit, de la même manière que vous revérifiez toute donnée de commande entrante avant qu’elle n’atteigne le flux de paiement.
4. Éliminez les doublons sur quote_id afin qu’une nouvelle tentative de livraison ne crée pas une double commande.
5. Accusez réception rapidement, traitez de manière asynchrone. Vous disposez de 10 secondes pour renvoyer un code 2xx — enregistrez la charge utile, renvoyez un 200, puis effectuez les tâches lourdes (téléchargements, modifications du panier, appels ERP) dans une tâche d’arrière-plan.

En résumé, un gestionnaire robuste se présente comme suit :

recevoir la requête POST
  → vérifier la signature du corps brut          (rejeter si invalide)
  → dédupliquer par rapport à `quote_id`                      (renvoyer 200 si déjà vu)
  → rechercher le jeton de transfert dans votre propre boutique  (ignorer s’il est inconnu)
  → enregistrer la charge utile, mettre la tâche en file d’attente en arrière-plan
  → renvoyer 200
tâche en arrière-plan
  → revalider le prix par rapport à son propre catalogue
  → ajouter l’article au panier / créer la commande

Dépannage

Prêt à créer ?

Le mode « Save/API » transforme Konfiwear en une interface de conception pour n’importe quelle pile e-commerce que vous utilisez. Activez-le dans Paramètres → Global → Appel à l’action, configurez la vérification de la signature, et votre plateforme recevra chaque design configuré avec les tarifs, les aperçus et les fichiers de production joints.

Commencez votre essai gratuit et connectez Konfiwear à votre plateforme dès aujourd’hui.