Saltar al contenido principal

Webhooks

Los webhooks permiten que NinoxNet notifique cambios de artículos hacia tu integración sin depender solamente de consultas periódicas.

Cuándo conviene usarlos​

  • reducir polling
  • mantener stock y precios más actualizados
  • acelerar sincronizaciones incrementales
Recomendación

Para una integración nueva, conviene implementar primero la lectura de catálogo y después sumar webhooks como mecanismo de actualización incremental.

Cómo se habilitan​

La configuración se coordina con NinoxNet. Para activarlos, debés informar:

  • URL HTTPS de destino
  • headers personalizados, si necesitás autenticación adicional
  • formato esperado del payload, si se acordó una variante específica

Requisitos del endpoint receptor​

Tu endpoint debe:

  • aceptar requests POST
  • procesar JSON
  • responder 200 OK cuando reciba correctamente el evento
  • responder rápido
Timeout

Si el endpoint no responde dentro de 10 segundos, el envío puede considerarse fallido.

Eventos contemplados​

Cambio de artículo​

Informa cambios de stock, precios, propiedades del artículo, variantes y clasificación comercial. El payload puede enviarse en dos formatos, según la configuración.

Formato plano​

ArticuloConCurva[]

Es el formato más práctico para la mayoría de las integraciones: cada variante llega como un registro independiente.

Formato agrupado​

Articulo

Conserva la curva y los tags dentro de un único objeto de artículo.

Coordinación previa

Si necesitás un formato específico, definilo al configurar el webhook con NinoxNet.

Artículo desactivado​

Cuando un artículo deja de participar en la integración, el webhook informa la baja lógica:

{
  articuloId: number;
  eliminado: true;
}

Recomendaciones de implementación​

  • validar autenticidad del request según la configuración acordada
  • registrar cada evento recibido
  • procesar de forma idempotente
  • desacoplar recepción y procesamiento con una cola o tarea interna, si el volumen lo justifica
  • mantener una resincronización completa periódica como mecanismo de respaldo

Estrategia sugerida​

sync inicial (GetData) → caché local → updates por webhook → resync completa periódica de respaldo
  1. sincronización inicial con GetData
  2. almacenamiento local del catálogo
  3. actualización incremental por webhook
  4. resincronización completa periódica respetando la frecuencia mínima de consulta

Relación con el resto de la integración​

Los webhooks complementan la integración, pero no reemplazan el alta inicial ni el modelado del catálogo. El punto de entrada general es Integración de terceros y la referencia de tipos está en Esquema de datos.