Saltar al contenido principal

Webhooks

Clione recibe webhooks de Shopify, BigCommerce y WooCommerce para que los cambios de producto de tu tienda lleguen a Clione sin un sync completo. Clione los registra cada vez que se guardan las credenciales de una tienda. En una tienda instalada con la app de Shopify de Clione, los registra Shopify al instalarla. Una tienda Shopify conectada con un access token permanente no recibe webhooks; el sync la mantiene al día. Cada entrega se autentica contra el secreto que Clione guarda para esa tienda antes de fiarse de nada de su contenido; una entrega que no pasa la comprobación se rechaza con 401 y nunca se aplica.

Los webhooks mantienen sincronizados los productos. Las categorías, colecciones y páginas se actualizan con el sync.

Un webhook de producto solo actualiza datos de catálogo: nunca lanza un enrichment.

Shopify​

Endpoint: POST /api/v1/webhooks/shopify (también se acepta en POST /api/v1/shopify/webhooks).

TopicQué hace Clione
products/createSincroniza el producto en Clione
products/updateSincroniza los cambios del producto
products/deleteElimina el producto
app/uninstalledDesactiva la tienda y deshace las señales que escribió Clione
customers/data_requestBusca en las conexiones de esa tienda Shopify los pedidos que indica orders_requested y registra lo que Clione guarda de ellos, que es el registro con el que se responde al cliente: de cada pedido, el número, la fecha, la moneda, el total, el origen de la visita (página de entrada, referrer, fuente, etiquetas de campaña) y las líneas (producto, cantidad, importe), y cuántas señales de pedido lo referencian. Solo lectura. Clione no guarda el nombre, el email, el teléfono ni la dirección de ningún cliente, así que no hay nada de eso que devolver
customers/redactBorra de las conexiones de esa tienda Shopify los pedidos que indica orders_to_redact, con sus líneas, el origen de la visita y la atribución a la IA, y borra las señales de pedido que referencian esos mismos ids. En Clione no hay nada más asociado a un cliente o a un pedido
shop/redactLlega 48 horas después de desinstalar y borra cada conexión inactiva instalada con la app de Clione, cada una en una sola transacción, con todos sus datos (catálogo, enrichments, FAQs, pedidos, ajustes), y la organización si era su última tienda y la creó la app. Mientras la organización siga existiendo, su registro de facturación de Shopify se conserva con el dominio de la tienda anonimizado. Una tienda reinstalada, o conectada como app personalizada, no se toca. Si el borrado falla, Clione responde con un error para que Shopify lo reintente

Firma. La cabecera X-Shopify-Hmac-Sha256 lleva el HMAC-SHA256 en base64 del cuerpo en bruto de la petición. Clione lo calcula con el secreto con el que se firman los webhooks de la tienda (el client secret de la app de Shopify propia de la tienda, o el secreto de la app de Clione si la tienda se conectó a través de ella) y compara en tiempo constante. La tienda se resuelve a partir de X-Shopify-Shop-Domain (un dominio *.myshopify.com; cualquier otra cosa da 400), y el topic a partir de X-Shopify-Topic.

BigCommerce​

Endpoint: POST /api/v1/bigcommerce/webhooks.

ScopeQué hace Clione
store/product/createdSincroniza el producto en Clione
store/product/updatedSincroniza los cambios del producto
store/product/deletedElimina el producto

Autenticación. BigCommerce no firma el cuerpo de los webhooks. Cuando Clione registra un hook, fija dos cabeceras que BigCommerce devuelve en cada entrega:

  • X-Clione-Store-Id: la tienda de Clione, contrastada con el producer del payload (stores/<hash>).
  • X-Clione-Webhook-Secret: un secreto aleatorio generado para esa tienda, comparado en tiempo constante con el que guarda Clione.

Una tienda desconocida o un secreto incorrecto dan 401.

WooCommerce​

Endpoint: POST /api/v1/woocommerce/webhooks?store=<store id>.

TopicQué hace Clione
product.createdSincroniza el producto en Clione
product.updatedSincroniza los cambios del producto
product.deletedElimina el producto

Firma. La cabecera X-WC-Webhook-Signature lleva el HMAC-SHA256 en base64 del cuerpo en bruto, firmado con un secreto por tienda que Clione fija al registrar el hook. La tienda sale del parámetro de query store, contrastado con X-WC-Webhook-Source. El ping que envía WooCommerce al crear un hook se responde con 200, para que el hook quede activo.

Eventos de pedido​

orders/create y orders/paid (Shopify) y store/order/created y store/order/statusUpdated (BigCommerce) se verifican igual y, si llegan, se registran como señales de pedido. Clione no los registra.

Respuestas​

EstadoSignificado
200Aceptado. Incluye los topics que Clione no gestiona y las tiendas inactivas: se acusa recibo para que la plataforma deje de reintentar, y se ignoran.
400Entrega mal formada: falta el topic o el scope, no hay id de producto o el dominio de la tienda no es válido.
401La firma o el secreto no se verificaron para ninguna tienda que tenga Clione.
500Solo topics de la app de Shopify: el secreto de la app no está configurado. Nunca se acepta un webhook sin firmar.