Cómo integrar los webhooks de Konfiwear con tu carrito personalizado (paso a paso)

Lo que vas a conseguir

En este tutorial, conectarás Konfiwear a cualquier plataforma que controles —una tienda de OpenCart, una tienda personalizada en PHP, un escaparate «headless»— utilizando el modo Guardar/API. Cuando un cliente termina de diseñar en el configurador 3D y hace clic en el botón de llamada a la acción (CTA), Konfiwear envía toda la información del diseño a tu punto final HTTPS: imágenes de vista previa, precios, desglose de tallas y referencias a los archivos de producción. A partir de ahí, tu código se encarga del resto: añade el artículo al carrito, crea un pedido o realiza cualquier otra acción que requiera tu flujo de trabajo.

Si utilizas Shopify o WooCommerce, no necesitas nada de esto: utiliza en su lugar las integraciones nativas con el carrito. El modo «Guardar/API» es para todos los demás.

Requisitos:

• Un espacio de trabajo de Konfiwear con acceso al modo Guardar/API
• Acceso de administrador a la configuración de tu espacio de trabajo
• Un punto final HTTPS accesible públicamente que pueda recibir solicitudes POST

Al finalizar, tendrás:

• El modo Save/API habilitado con tu URL de webhook configurada y probada
• Verificación de firma que protege tu punto final frente a solicitudes falsificadas
• Tu propio contexto de sesión fluyendo desde tu página, a través del iframe del personalizador, de vuelta a tu servidor

Paso 1 — Activar el modo Guardar/API

1. En Konfiwear, abre tu espacio de trabajo de equipo.
2. Ve a Configuración → Global → Llamada a la acción.
3. En Modo de acción, selecciona Guardar / API.
4. En el campo URL del webhook, introduce tu punto final HTTPS (por ejemplo, https://shop.example.com/konfiwear/webhook).
5. Haz clic en Enviar prueba: Konfiwear envía una carga útil de muestra a tu punto final y te muestra el estado HTTP y el tiempo de respuesta.
6. Haz clic en Guardar cambios.

Paso 2 — Comprender la carga útil

Cuando un comprador envía un diseño, tu punto final recibe un evento design.saved.v3:

{
  "event": "design.saved.v3",
  "transaction_id": "order-draft-8841",
  "session": {
    "id": "uuid",
    "passthrough": { "s": "tu-valor-devuelto" }
  },
  "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" },
      "recursos": {
        "vistas previas": [{ "estado": "listo", "url": "https://..." }],
        "ficha_técnica": { "estado": "pendiente", "url": null }
      }
    }
  ]
}

A continuación se muestra una entrega real inspeccionada en un depurador de webhooks; fíjate en los encabezados de solicitud X-Konfiwear-Event y X-Konfiwear-Signature junto al cuerpo JSON:

• transaction_id: una referencia que incluyes en la URL del personalizador y que se te devuelve (Paso 4).
• session.passthrough: valores adicionales que has configurado para que se devuelvan, también procedentes de la URL (Paso 4). Solo aparece si se ha configurado.
• quote_id: el ID único de este envío. Úsalo para eliminar duplicados.
• assets: imágenes de vista previa y archivos de producción. Los paquetes técnicos y los archivos de impresión se generan en segundo plano; al principio aparecen como «pendientes», y un evento de seguimiento design.assets.ready llega a la misma URL cuando cada archivo está listo.

Paso 3 — Verificar las firmas (recomendado)

Antes de confiar en cualquier dato del cuerpo de un webhook, confirma que la solicitud procede realmente de Konfiwear.

Genera tu clave secreta: en Configuración → Global → Llamada a la acción → Firma de webhooks, haz clic en Generar clave secreta y cópiala inmediatamente; solo se muestra una vez. Guárdalo en una variable de entorno, nunca en tu código ni en tu repositorio. Si alguna vez se filtra, regénéralo y actualiza tu entorno.

$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); // se puede procesar con seguridad

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

El único error habitual: comprueba siempre el cuerpo de la solicitud sin procesar. Si tu framework analiza primero el JSON y luego lo conviertes de nuevo en cadena, el resumen no coincidirá.

Paso 4 — Incrusta el personalizador y pasa tu propio contexto

La mayoría de las integraciones de Save/API incrustan el personalizador en un iframe. El reto: cuando el webhook llega a tu servidor, ¿cómo sabes a qué cliente concreto pertenece? No puedes confiar en tu cookie de sesión, ya que los navegadores bloquean las cookies de terceros dentro de los iframes. En su lugar, pasa tu contexto a través de la URL y deja que Konfiwear lo devuelva.

Añade una referencia de tu elección a la URL que cargas en el iframe:

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

Konfiwear la devuelve tal cual en cada webhook de esa sesión. Génala en el lado del servidor, almacénala junto con la sesión del comprador y dispondrás de una clave de unión fiable.

Parámetros personalizados: paso de sesión

Si tu plataforma ya genera un token de sesión con su propio nombre de parámetro (por ejemplo, s):

1. En Configuración → Global → Llamada a la acción, añade el nombre del parámetro a Parámetros de paso de sesión.
2. Añádelo al final de la URL de tu iframe: ...?s=7a6f2ca2f15d3a691aaac9ecbc
3. Recupéralo del webhook en session.passthrough.s.

Solo se devuelven los nombres de parámetros que figuran en tu lista de permitidos configurada; cualquier otro elemento de la URL se ignora. Los nombres design, quote, rev, saved y transaction_id están reservados.

Konfiwear también envía un mensaje del navegador a tu página principal cuando se realiza un envío con éxito (konfiwear:design.saved), de modo que tu interfaz de usuario puede reaccionar al instante —mostrar una confirmación, redirigir al carrito— sin necesidad de consultar tu servidor.

Paso 5 — Gestiona el webhook de forma segura

Las prácticas estándar de seguridad para webhooks se aplican a Konfiwear del mismo modo que a Stripe o Shopify:

1. Verifica primero la firma. Se puede acceder a la URL de tu webhook desde la red pública de Internet; la firma es el candado. Rechaza cualquier cosa que falle.
2. Trata los valores devueltos como claves de búsqueda, no como autenticación. transaction_id y session.passthrough proceden de una URL del navegador del comprador. Úsalos para encontrar la sesión correspondiente en tu propia tienda y confirma que esa sesión es una que tú has emitido y que sigue activa, antes de añadir nada a un carrito activo.
3. Vuelve a validar los precios con tu propio catálogo antes de cobrar a nadie, del mismo modo que volverías a comprobar cualquier dato de un pedido entrante antes de que llegue al flujo de pago.
4. Elimina duplicados por quote_id para que un reintento de entrega no genere un pedido doble.
5. Confirma rápidamente, procesa de forma asíncrona. Tienes 10 segundos para devolver un código 2xx: guarda la carga útil, responde con 200 y realiza las tareas más pesadas (descargas, modificaciones del carrito, llamadas al ERP) en un proceso en segundo plano.

En resumen, un gestor robusto tiene el siguiente aspecto:

recibir POST
  → verificar la firma sobre el cuerpo sin procesar          (rechazar si no es válida)
  → eliminar duplicados por `quote_id`                      (devolver 200 si ya se ha visto)
  → buscar el token de paso en la propia tienda  (ignorar si se desconoce)
  → almacenar la carga útil, poner en cola la tarea en segundo plano
  → devolver 200
tarea en segundo plano
  → volver a validar el precio con el catálogo propio
  → añadir el artículo al carrito / crear el pedido

Resolución de problemas

¿Listo para crear?

El modo «Guardar/API» convierte Konfiwear en un front-end de diseño para cualquier plataforma de comercio electrónico que utilices. Actívalo en Configuración → Global → Llamada a la acción, configura la verificación de la firma y tu plataforma recibirá todos los diseños configurados con precios, vistas previas y archivos de producción adjuntos.

Empieza tu prueba gratuita y conecta Konfiwear a tu plataforma hoy mismo.