Saltar al contenido principal

Webhooks

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

Cuándo conviene usarlos​

Los webhooks son útiles para:

  • 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 Ninox. 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​

Se usa para informar cambios de:

  • stock
  • precios
  • propiedades del artículo
  • variantes
  • clasificación comercial

El payload puede enviarse en dos formatos, según la configuración de la integración.

Formato plano​

ArticuloConCurva[]

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

Formato agrupado​

Articulo

Este formato 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 momento de configurar el webhook con Ninox.

Artículo desactivado​

Cuando un artículo deja de participar en la integración, el webhook puede informar la baja lógica.

{
  articuloId: number;
  eliminado: true;
}

Recomendaciones de implementación​

Al recibir webhooks, conviene:

  • 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​

Una estrategia simple y robusta suele ser:

  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 proceso de alta inicial ni el modelado del catálogo. La documentación base está en Integración de terceros y la referencia de tipos en Esquema de datos.