Webhook

Los webhooks son funciones que te permiten recibir notificaciones en tiempo real cuando ocurren ciertos eventos en BoxHero.

---

Registro

Puedes registrar un webhook en Configuración > Integraciones y API en tu equipo de BoxHero.

Comportamiento de entrega y reintento

Cuando ocurre un evento, BoxHero envía una solicitud HTTP POST a tu endpoint de webhook registrado. El cuerpo de la solicitud contiene una carga útil JSON que describe el evento.

• Si tu servidor responde con HTTP 200 OK, el evento se considera entregado correctamente.

• Si tu servidor responde con cualquier código de estado distinto de 200, BoxHero lo trata como un fallo temporal y reintenta la entrega hasta 3 veces.

Estructura de la carga útil del webhook

Todos los eventos de webhook se entregan con la siguiente estructura JSON en el cuerpo de la solicitud:

{
  "id": "1234", // ID único del evento
  "topic": "txs/new", // Tema del evento
  "version": 1, // Versión del esquema de la carga útil
  "payload": { // Datos específicos del evento
    ...
  },
  "created_time": "2025-08-06T09:20:48.623Z" // Marca temporal de la ocurrencia del evento (ISO 8601)
}

---

Orden de eventos

BoxHero no garantiza el orden de entrega de los eventos. Por ejemplo, un item/new evento puede llegar después de un item/delete evento para el mismo artículo.

El created_time campo en la carga útil del evento representa la hora real del evento. Implementa una lógica idempotente y tolerante al orden en tu controlador de webhook para manejar los eventos de forma fiable.

Temas de eventos

Si necesitas soporte para temas de eventos adicionales, ponte en contacto con Soporte.

txs/new

Se activa cuando ocurre una transacción de inventario (Entrada de stock / Salida de stock / Ajuste de stock / Movimiento de stock).

Nota: Este evento no se activa para ajustes creados mediante ediciones masivas o importaciones (p. ej., al agregar o actualizar artículos mediante Excel).

ObligatorioObligatorio

Campo	Obligatorio	Descripción
id		ID único de la transacción
type		Tipo de transacción (in, out, adjust, move)
socio		Socio
partner.id		ID único del socio
partner.name		Nombre del socio
partner.deleted		Si el socio está eliminado
from_location		Ubicación de origen
from_location.id		ID único de la ubicación de origen
from_location.name		Nombre de la ubicación de origen
from_location.deleted		Si la ubicación de origen está eliminada
to_location		Ubicación de destino
to_location.id		ID único de la ubicación de destino
to_location.name		Nombre de la ubicación de destino
to_location.deleted		Si la ubicación de destino está eliminada
items		Líneas de artículos en la transacción
items.id		ID único del artículo
items.name		Nombre del artículo
items.quantity		Cambio de inventario debido a entrada/salida/ajuste/movimiento de stock
items.deleted		Si el artículo está eliminado
items.from_location_new_stock_level		El nivel de stock en la ubicación de origen después de la transacción
items.to_location_new_stock_level		El nivel de stock en la ubicación de destino después de la transacción
transaction_time		Hora de la transacción (p. ej., hora de entrada/salida de stock)
created_at		La hora en que se creó la transacción
created_by		Miembro que creó la transacción
created_by.id		ID único del miembro
created_by.name		Nombre del miembro
created_by.deleted		Si el miembro está eliminado
count_of_items		El número de artículos
total_quantity		La cantidad total de cambio de inventario
url		URL para ver la página de detalles de la transacción
memo		Notas relacionadas con la transacción

Ejemplo de carga útil del webhook – Entrada de stock Evento

{
  "id": 16160911,
  "type": "in",
  "to_location": {
    "id": 52766,
    "name": "Almacén 3",
    "deleted": false
  },
  "items": [
    {
      "id": 14277699,
      "name": "belif Cleansing Gel Oil Enriched",
      "quantity": 2,
      "deleted": false,
      "to_location_new_stock_level": 3
    },
    {
      "id": 14277698,
      "name": "belif Aqua Bomb Jelly Cleanser",
      "quantity": 2,
      "deleted": false,
      "to_location_new_stock_level": 5
    }
  ],
  "transaction_time": "2023-04-25T05:42:27.545Z",
  "created_at": "2023-08-14T05:14:29.499Z",
  "created_by": {
    "id": 201345,
    "name": "corp",
    "deleted": false
  },
  "count_of_items": 2,
  "total_quantity": 4,
  "url": "https://web.boxhero-app.com/team/149058/mode/0#/tx/16160911"
}

Ejemplo de carga útil del webhook – Mover stock Evento

{
  "id": 3692714,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "Almacén 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "Almacén 3",
    "deleted": false
  },
  "items": [
    {
      "id": 14873303,
      "name": "Auto liner 3.5mm",
      "quantity": 1,
      "deleted": false,
      "from_location_new_stock_level": -1,
      "to_location_new_stock_level": 1
    }
  ],
  "transaction_time": "2025-04-25T05:42:27.545Z",
  "created_at": "2025-04-25T05:42:27.545Z",
  "created_by": {
    "id": 176829,
    "name": "Tony Lee",
    "deleted": false
  },
  "count_of_items": 1,
  "total_quantity": 1,
  "url": "https://web.boxhero-app.com/team/150581/mode/2#/ltx/3692714"
}

txs/edit

Se envía cuando una transacción de inventario existente (Entrada de stock / Salida de stock / Ajuste de stock / Movimiento de stock) es editada.

ObligatorioObligatorio

Campo	Obligatorio	Descripción
id		ID único de la transacción
type		Tipo de transacción (in, out, adjust, move)
socio		Socio
partner.id		ID único del socio
partner.name		Nombre del socio
partner.deleted		Si el socio está eliminado
from_location		Ubicación de origen
from_location.id		ID único de la ubicación de origen
from_location.name		Nombre de la ubicación de origen
from_location.deleted		Si la ubicación de origen está eliminada
to_location		Ubicación de destino
to_location.id		ID único de la ubicación de destino
to_location.name		Nombre de la ubicación de destino
to_location.deleted		Si la ubicación de destino está eliminada
items		Líneas de artículos en la transacción
items.id		ID único del artículo
items.name		Nombre del artículo
items.quantity		Cambio de cantidad debido a la transacción (entrada/salida/ajuste/movimiento)
items.deleted		Si el artículo está eliminado
items.from_location_new_stock_level		El nivel de stock en la ubicación de origen después de la transacción
items.to_location_new_stock_level		El nivel de stock en la ubicación de destino después de la transacción
transaction_time		Hora de la transacción (p. ej., hora de entrada/salida de stock)
created_at		La hora en que se creó la transacción
created_by		Miembro que creó la transacción
created_by.id		ID único del miembro
created_by.name		Nombre del miembro
created_by.deleted		Si el miembro está eliminado
count_of_items		El número de artículos
total_quantity		La cantidad total de cambio de inventario
url		URL para ver la página de detalles de la transacción
memo		Notas relacionadas con la transacción
revisión		Número de versión actual de la transacción, comenzando desde 1

Ejemplo de carga útil del webhook – Transacción editada Entrada de stock Transacción

{
  "id": 16160911,
  "type": "in",
  "to_location": {
    "id": 52766,
    "name": "Almacén 3",
    "deleted": false
  },
  "items": [
    {
      "id": 14277699,
      "name": "belif Cleansing Gel Oil Enriched",
      "quantity": 2,
      "deleted": false,
      "to_location_new_stock_level": 3
    },
    {
      "id": 14277698,
      "name": "belif Aqua Bomb Jelly Cleanser",
      "quantity": 2,
      "deleted": false,
      "to_location_new_stock_level": 5
    }
  ],
  "transaction_time": "2023-04-25T05:42:27.545Z",
  "created_at": "2023-08-14T05:14:29.499Z",
  "created_by": {
    "id": 201345,
    "name": "corp",
    "deleted": false
  },
  "count_of_items": 2,
  "total_quantity": 4,
  "url": "https://web.boxhero-app.com/team/149058/mode/0#/tx/16160911"
}

Ejemplo de carga útil del webhook – Transacción editada Mover stock Transacción

{
  "id": 3692714,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "Almacén 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "Almacén 3",
    "deleted": false
  },
  "items": [
    {
      "id": 14873303,
      "name": "Auto liner 3.5mm",
      "quantity": 1,
      "deleted": false,
      "from_location_new_stock_level": -1,
      "to_location_new_stock_level": 1
    }
  ],
  "transaction_time": "2023-04-25T05:42:27.545Z",
  "created_at": "2023-04-25T05:42:27.545Z",
  "created_by": {
    "id": 176829,
    "name": "Joy Kim",
    "deleted": false
  },
  "count_of_items": 1,
  "total_quantity": 1,
  "url": "https://web.boxhero-app.com/team/150581/mode/2#/ltx/3692714"
}

txs/delete

Se envía cuando una transacción de inventario es eliminada.

Campo	Descripción
id	ID único de la transacción
revisión	Número de versión actual de la transacción, comenzando desde 1

Ejemplo de carga útil del webhook – Transacción eliminada

/{
  "id": 27036740,
  "revision": 2
}

item/new

Se envía cuando se agrega un nuevo artículo al inventario del equipo.

Nota: Este evento es no activado al usar la Agregar variantes de artículo función o al importar artículos mediante Importar Excel.

Obligatorio

Campo	Descripción
id	ID del artículo
nombre	Nombre del artículo
sku	SKU
código de barras	Código de barras
photo_url	URL de la foto
costo	Costo
precio	Precio
atributos	Atributos

Ejemplo de carga útil – Artículo creado

{
  "id": 26122826,
  "name": "belif Peat Miracle Revital Cream",
  "sku": "SKU-YH2361KI",
  "barcode": "2002074321218",
  "photo_url": "https://d3l9wd8kivvlqy.cloudfront.net/ap-northeast-2/image-up-ap-northeast-2/30b0cc84-601d-493d-87fd-b7e8b5825601",
  "cost": "50000",
  "price": "65000",
  "attrs": [
    {
      "id": 413101,
      "name": "Categoría",
      "type": "text",
      "value": "Base"
    },
    {
      "id": 459264,
      "name": "Fecha de caducidad",
      "type": "date",
      "value": "2027-08-07"
    },
    {
      "id": 668272,
      "name": "Stock de seguridad",
      "type": "number",
      "value": 33
    }
  ]
}

item/edit

Se envía cuando se edita un artículo existente.

Nota: Este evento es no activado fo mediante ediciones masivas realizadas a través de Centro de datos > Artículo o mediante la Importar Excel función.

Obligatorio

Campo	Descripción
id	ID del artículo
nombre	Nombre del artículo
sku	SKU
código de barras	Código de barras
photo_url	URL de la foto
costo	Costo
precio	Precio
atributos	Atributos

Ejemplo de carga útil – Artículo actualizado

{
  "id": 26122826,
  "name": "belif Peat Miracle Revital Cream",
  "sku": "SKU-YH2361KI",
  "barcode": "2002074321218",
  "photo_url": "https://d3l9wd8kivvlqy.cloudfront.net/ap-northeast-2/image-up-ap-northeast-2/30b0cc84-601d-493d-87fd-b7e8b5825601",
  "cost": "50000",
  "price": "65000",
  "attrs": [
    {
      "id": 413101,
      "name": "Categoría",
      "type": "text",
      "value": "Base"
    },
    {
      "id": 459264,
      "name": "Fecha de caducidad",
      "type": "date",
      "value": "2027-08-07"
    },
    {
      "id": 668272,
      "name": "Stock de seguridad",
      "type": "number",
      "value": 33
    }
  ]
}

item/delete

Se envía cuando se elimina un artículo del inventario del equipo.

Nota: Este evento es no activado para eliminaciones masivas realizadas a través de Centro de datos > Artículo.

Campo	Descripción
id	ID del artículo

Ejemplo de carga útil – Artículo eliminado

{
  "id": 26122826
}