Webhooks

Descripción General

Los webhooks son callbacks HTTP que Nilo utiliza para notificar a tu sistema sobre eventos en tiempo real. A diferencia de los endpoints regulares de API donde tú haces solicitudes a Nilo, los webhooks son endpoints que tú debes implementar en tu sistema para recibir notificaciones de Nilo.

Requisitos Importantes de Implementación

1. Disponibilidad del Endpoint: Tus endpoints deben ser accesibles públicamente
2. Estructura de Ruta: Debes implementar las rutas exactas como las especifica Nilo
3. Tiempo de Respuesta: Tus endpoints deben responder dentro de un período de tiempo razonable
4. Código de Respuesta: Debe devolver HTTP 200 para confirmar la recepción
5. Cumplimiento del Contrato: Debe aceptar la estructura exacta del cuerpo de la solicitud como se especifica

Webhooks Disponibles

Webhook de Orden Creada

POST/webhooks/order

Este webhook se activa cuando se crea una nueva orden en la plataforma Nilo. Tu sistema debe implementar este endpoint para recibir notificaciones de órdenes.

Estructura del Cuerpo de la Solicitud

Campo	Tipo	Descripción
id	integer	ID de la orden en el sistema Nilo
buyer	object	Información sobre el comprador
address	object	Detalles de la dirección de entrega
products	array	Lista de productos ordenados
promotions	object	Contiene recompensas y descuentos aplicados a la orden
status	string	Estado de la orden (siempre "PENDING" para nuevas)

Estructura de Promociones

Campo	Tipo	Descripción
rewards	array	Lista de recompensas para la orden
discounts	array	Lista de descuentos para la orden

Estructura de Recompensa

Campo	Tipo	Descripción
promoInternalCode	string	Código interno de la promoción
quantity	number	Cantidad de productos a ser recompensados
products	array	Lista de productos a ser recompensados (siempre uno)

Estructura de Producto de Recompensa

Campo	Tipo	Descripción
internalCode	string	Código interno del producto
units	number	Unidades del producto

Estructura de Descuento

Campo	Tipo	Descripción
promoInternalCode	string	Código interno de la promoción
appliedDiscountPercentage	number	Porcentaje de descuento aplicado
appliedDiscountAmount	number	Monto de descuento aplicado
products	array	Lista de productos a ser descontados

Estructura de Producto de Descuento

Campo	Tipo	Descripción
internalCode	string	Código interno del producto
units	number	Unidades del producto

Ejemplo del Cuerpo de la Solicitud

{
  "id": 10,
  "buyer": {
    "storeCode": "10",
    "routeCode": "10"
  },
  "address": {
    "internalCode": "1234",
    "addressLine": "25 de mayo 1200, Buenos aires, Argentina",
    "apartmentNumber": "2",
    "zipCode": "2400"
  },
  "products": [
    {
      "code": "22222.1",
      "units": 2,
      "quantity": 10,
      "unitFinalPrice": {
        "value": 0.9,
        "text": "USD 0.9"
      },
      "unitPrice": {
        "value": 1,
        "text": "USD 1"
      },
      "subtotal": {
        "value": 10,
        "text": "USD 10"
      },
      "total": {
        "value": 9,
        "text": "USD 9"
      }
    }
  ],
  "promotions": {
    "rewards": [
      {
        "promoInternalCode": "5425",
        "quantity": 1,
        "products": [
          {
            "internalCode": "45678",
            "units": 1
          }
        ]
      }
    ],
    "discounts": [
      {
        "promoInternalCode": "1234",
        "appliedDiscountPercentage": 10,
        "appliedDiscountAmount": 0.1,
        "products": [
          {
            "internalCode": "22222.1",
            "units": 2
          }
        ]
      }
    ]
  },
  "status": "PENDING",
  "createdAt": "2025-12-03T10:15:30Z"
}

Webhook de Orden Cancelada

PUT/webhooks/order

Este webhook se activa cuando se cancela una orden en la plataforma Nilo. Tu sistema debe implementar este endpoint para recibir notificaciones de cancelación.

Estructura del Cuerpo de la Solicitud

Campo	Tipo	Descripción
id	integer	ID de la orden en el sistema Nilo
status	string	Siempre "CANCELLED" para eventos de cancelación
reason	string	Razón legible de la cancelación
code	string	Código de cancelación (ej., "NEW_ORDER")
buyer	object	Información sobre el comprador

Ejemplo del Cuerpo de la Solicitud

{
  "id": 10,
  "status": "CANCELLED",
  "reason": "Realizaré un nuevo pedido",
  "code": "NEW_ORDER",
  "buyer": {
    "storeCode": "1234"
  }
}

Webhook de Eventos de Usuario de Tienda

POST/webhooks/store/user

Este webhook se activa para eventos relacionados con usuarios de tienda (creación/eliminación). Tu sistema debe implementar este endpoint para recibir notificaciones de eventos de usuario.

Estructura del Cuerpo de la Solicitud

Campo	Tipo	Descripción
subject	string	Tipo de evento ("user-created" o "user-deleted")
store	object	Información de la tienda
user	object	Información del usuario

Ejemplo del Cuerpo de la Solicitud

{
  "subject": "user-created",
  "store": {
    "id": 1,
    "internalCode": "123565"
  },
  "user": {
    "username": "+5042345213343",
    "name": "nombre del vendedor"
  }
}

Webhook de Creación de Ticket de Soporte

POST/webhooks/support/create-ticket

Este webhook se activa cuando se crea un nuevo ticket de soporte en la plataforma Nilo. Tu sistema debe implementar este endpoint para recibir notificaciones de tickets de soporte.

Estructura del Cuerpo de la Solicitud

Campo	Tipo	Requerido	Descripción
ticket_id	string	Sí	Identificador único del ticket
client_internal_code	string	Sí	Código interno del cliente
client_name	string	Sí	Nombre del cliente
phone_number	string	No	Número de teléfono de contacto
email	string	No	Dirección de correo electrónico
description	string	Sí	Descripción del problema de soporte
issue_type	string	Sí	Tipo de problema de soporte

Ejemplo del Cuerpo de la Solicitud

{
  "ticket_id": "1122",
  "client_internal_code": "1122",
  "client_name": "Nilo Store",
  "phone_number": "+5042345213343",
  "email": "seller@nilo.com",
  "description": "Necesito soporte para mi cuenta",
  "issue_type": "Soporte de cuenta"
}

Respuesta

Tu endpoint debe devolver un código de estado 200 para confirmar la recepción exitosa de la notificación del webhook.

Webhook de Información Adicional de Ticket de Soporte

POST/webhooks/support/ticket-additional-info-received

Este webhook se activa cuando hay una respuesta a una solicitud de información adicional para un ticket de soporte. Tu sistema debe implementar este endpoint para recibir estas notificaciones.

Estructura del Cuerpo de la Solicitud

Campo	Tipo	Requerido	Descripción
ticket_id	string	Sí	ID del ticket generado por Nilo
external_ticket_id	string	No	ID del ticket generado por el proveedor de tickets (si está disponible)
client_internal_code	string	Sí	Código interno del cliente
client_email	string	Sí	Dirección de correo electrónico del cliente
response	string	Sí	La respuesta a la solicitud de información adicional del cliente

Ejemplo del Cuerpo de la Solicitud

{
  "ticket_id": "1122",
  "external_ticket_id": "EXT-5678",
  "client_internal_code": "1122",
  "client_email": "seller@nilo.com",
  "response": "Aquí está la información adicional que solicitaste"
}

Respuesta

Tu endpoint debe devolver un código de estado 200 para confirmar la recepción exitosa de la notificación del webhook.

Guías de Implementación

1. Configuración de Endpoints

   • Implementar todos los endpoints de webhook requeridos
   • Usar rutas exactas como se especifica
   • Aceptar métodos POST/PUT según se indica
   • Devolver HTTP 200 en recepción exitosa

2. Manejo de Errores

   • Implementar manejo de errores apropiado
   • Registrar payloads de webhook para depuración
   • Manejar notificaciones duplicadas adecuadamente
   • Implementar mecanismos de reintento si es necesario

3. Consideraciones de Seguridad

   • Validar fuente del webhook
   • Proteger acceso al endpoint
   • Implementar HTTPS
   • Monitorear por abuso

4. Rendimiento

   • Procesar webhooks de forma asíncrona
   • Responder rápidamente (menos de 10 segundos)
   • Escalar para alto volumen
   • Monitorear salud del endpoint

Pruebas de Webhooks

1. Configuración del Ambiente de Pruebas

   • Usar un endpoint accesible públicamente
   • Probar con payloads de ejemplo
   • Verificar códigos de respuesta
   • Monitorear procesamiento

2. Escenarios Comunes de Prueba

   • Creación de nueva orden
   • Cancelación de orden
   • Eventos de usuario
   • Condiciones de error

Mejores Prácticas

1. Confiabilidad

   • Implementar idempotencia
   • Almacenar datos crudos del webhook
   • Procesar de forma asíncrona
   • Manejar reintentos apropiadamente

2. Monitoreo

   • Registrar todas las llamadas webhook
   • Rastrear tiempos de respuesta
   • Monitorear tasas de error
   • Configurar alertas

3. Mantenimiento

   • Pruebas regulares
   • Actualizar implementaciones
   • Monitorear cambios
   • Mantener documentación