Suscripción de Webhook para notificar Eventos

La funcionalidad de Webhook permite notificar a los sistemas externos del cliente (ERP, middleware, integradores) cada vez que ocurre un evento en Janis: un pedido listo para facturar, una entrega despachada, un cambio de stock, entre otros. Los Webhooks se configuran desde Webhooks, creando una suscripción nueva.

1. Resumen

Al crear un Webhook se configura:

• Nombre.
• El/los evento/s que se quieren notificar. Ver Eventos disponibles.
• Filtros.
• URL asociada al endpoint.
• Los headers, en caso de que el endpoint así lo requiera.

Cada notificación identifica el evento con tres datos: el servicio que lo emite (service), la entidad afectada (entity) y el nombre del evento (eventName). Por ejemplo, la notificación de un pedido "Listo para facturar" tiene la siguiente estructura:

{
  "service": "oms",
  "entity": "order",
  "eventName": "ready-for-invoice",
  "eventDate": "2024-04-03T12:09:00.000Z",
  "metadata": {
    "id": "<YOUR_ORDER_ID>"
  }
}

Una vez que la suscripción fue configurada, se envía un POST (incluyendo los headers configurados) con el siguiente body:

{
  "setup": true
}

Para mayor información, consultar la documentación técnica de webhooks.

2. Eventos disponibles

A continuación se listan los eventos que se pueden notificar, agrupados por el servicio que los emite. Para cada evento se indica la entidad (entity) y el nombre del evento (eventName) tal como llegan en la notificación.

📘

Detalle técnico de cada evento

La estructura completa de cada notificación (campos de metadata, tipos y ejemplos) se encuentra en la sección Webhooks de la documentación técnica de cada servicio, en docs.janis.in. El listado de eventos puede crecer a medida que se incorporan nuevas funcionalidades.

OMS (Pedidos)

Servicio oms, entidad order. Detalle técnico: Webhooks de OMS.

Anulación de factura

Al ejecutar la acción Cancelar factura desde el detalle de un pedido (Pedidos → detalle del pedido → Cancelar factura), Janis emite el evento oms:order:invoice-canceled una única vez por cada anulación. La suscripción se crea de forma manual: mientras no exista una suscripción activa apuntando al endpoint, la anulación no se notifica.

{
  "service": "oms",
  "entity": "order",
  "eventName": "invoice-canceled",
  "eventDate": "2026-08-11T19:52:09.819Z",
  "metadata": {
    "id": "<YOUR_ORDER_ID>",
    "commerceId": "<YOUR_COMMERCE_ID>",
    "commerceSequentialId": "<YOUR_COMMERCE_SEQUENTIAL_ID>",
    "orderGroupId": "<YOUR_ORDER_GROUP_ID>",
    "orderGroupCommerceId": "<YOUR_ORDER_GROUP_COMMERCE_ID>",
    "sellerSalesChannelId": "<YOUR_SALES_CHANNEL_ID>",
    "sellerSalesChannelReferenceId": "<YOUR_SALES_CHANNEL_REFERENCE_ID>",
    "sellerSalesChannelName": "<YOUR_SALES_CHANNEL_NAME>",
    "carrierRefId": "<YOUR_CARRIER_REF_ID>",
    "invoiceIds": ["<YOUR_INVOICE_ID>"],
    "invoices": [
      { "id": "<YOUR_INVOICE_ID>", "number": "<YOUR_INVOICE_NUMBER>", "value": 235.67 }
    ]
  }
}

🚧

El campo invoices puede no llegar

Si el pedido conservaba solo los identificadores de sus facturas, la notificación viaja sin el campo invoices. El campo invoiceIds siempre está presente, así que conviene tomarlo como referencia principal al procesar el evento.

Delivery (Rutas y entregas)

Servicio delivery. Detalle técnico: Webhooks de Delivery. Para un caso de uso con operadores logísticos, ver Janis genera la ruta con un shipping.

TMS (Rutas)

Servicio tms, entidad route. Detalle técnico: Webhooks de TMS.

WMS (Inventario y movimientos)

Servicio wms. Detalle técnico: Webhooks de WMS.

Picking

Servicio picking, entidad session. Detalle técnico: Webhooks de Picking.

Control

Servicio control, entidad control. Detalle técnico: Webhooks de Control.

Catalog

Servicio catalog. Detalle técnico: Webhooks de Catalog.

Pricing

Servicio pricing, entidad skuPrice. Detalle técnico: Webhooks de Pricing.

Integración con VTEX

CSX (Atención al cliente)

Servicio csx, entidad claim. Detalle técnico: Webhooks de CSX.

3. Configuración de filtros

Janis también permite configurar filtros para realizar o no las notificaciones en base al contenido que tenga el webhook.

Para configurar un filtro se debe ingresar el contenido por el que se requiere filtrar dentro del campo Filtro.

El filtro se aplica sobre los datos de la notificación, por lo que conviene revisar primero la estructura del evento en la documentación técnica de su servicio (ver Eventos disponibles). El siguiente ejemplo muestra la notificación de una entrega del servicio de Delivery:

{
  "service": "delivery",
  "entity": "shipping",
  "eventName": "scheduled",
  "eventDate": "2024-04-03T12:09:00.000Z",
  "metadata": {
    "id": "<YOUR_SHIPPING_ID>",
    "status": "scheduled",
    "displayId": "<YOUR_SHIPPING_DISPLAY_ID>",
    "refId": "<YOUR_SHIPPING_REF_ID>",
    "trackingId": "<YOUR_TRACKING_ID>",
    "realTimeId": "<YOUR_REAL_TIME_ID>",
    "integ": "uber",
    "type": "express_delivery",
    "shippingTypeId": "<YOUR_SHIPPING_TYPE_ID>",
    "shippingTypeTitle": "Standard delivery",
    "carrierId": "<YOUR_CARRIER_ID>",
    "carrierName": "Standard delivery Uber",
    "companyId": "<YOUR_COMPANY_ID>",
    "companyName": "Uber Express",
    "price": 10
  }
}

En función de la notificación anterior, si se necesitara notificar vía webhook solo las entregas de una integración de Delivery puntual, los datos cargados en el filtro deberían ser los siguientes:

{
  "type": "object",
  "properties": {
    "integ": {
      "const": "uber"
    }
  },
  "required": ["integ"]
}

4. Reintentos

Janis realiza hasta 7 reintentos frente a respuestas no exitosas del endpoint. Para conocer mayor detalle de la política de reintentos, se sugiere revisar la siguiente documentación.

Para recomendaciones sobre cómo implementar el endpoint que recibe las notificaciones, ver Webhooks: Buenas prácticas.