Webhook

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

---

Registro

Puede registrar un webhook en Configuración > Integraciones y API en su equipo BoxHero.

Comportamiento de entrega y reintento

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

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

• Si su 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 del payload 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 del payload
  "payload": { // Datos específicos del evento
    ...
  },
  "created_time": "2025-08-06T09:20:48.623Z" // Marca de tiempo de ocurrencia del evento (ISO 8601)
}

---

Orden de los eventos

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

La created_time el campo en el payload del evento representa la hora real del evento. Implemente lógica idempotente y tolerante al orden en su manejador de webhook para procesar los eventos de forma fiable.

Temas de evento

Si necesita soporte para temas de evento adicionales, póngase en contacto con Soporte.

txs/new

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

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

Campo	Requerido	Descripción
id		ID único de la transacción
type		Tipo de transacción (in, out, adjust, move)
socio		Partner
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		Nivel de stock en la ubicación de origen después de la transacción
items.to_location_new_stock_level		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		La cantidad de artículos
total_quantity		La cantidad total de cambio de inventario
url		Dirección URL para ver la página de detalles de la transacción
memo		Notas relacionadas con la transacción

Ejemplo de payload del webhook – Entrada de stock Evento

{
  "id": 16160911,
  "type": "in",
  "to_location": {
    "id": 52766,
    "name": "Warehouse 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 payload del webhook – Mover stock Evento

{
  "id": 3692714,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "Warehouse 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "Warehouse 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 / Ajustar stock / Mover stock) es editada.

Campo	Requerido	Descripción
id		ID único de la transacción
type		Tipo de transacción (in, out, adjust, move)
socio		Partner
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 (in/out/adjust/move)
items.deleted		Si el artículo está eliminado
items.from_location_new_stock_level		Nivel de stock en la ubicación de origen después de la transacción
items.to_location_new_stock_level		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		La cantidad de artículos
total_quantity		La cantidad total de cambio de inventario
url		Dirección URL para ver la página de detalles de la transacción
memo		Notas relacionadas con la transacción
revision		Número de versión actual de la transacción, comenzando desde 1

Ejemplo de payload del webhook – Editado Entrada de stock Transacción

{
  "id": 16160911,
  "type": "in",
  "to_location": {
    "id": 52766,
    "name": "Warehouse 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 payload del webhook – Editado Mover stock Transacción

{
  "id": 3692714,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "Warehouse 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "Warehouse 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
revision	Número de versión actual de la transacción, comenzando desde 1

Ejemplo de payload 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 se no activa al usar la función Agregar variantes de artículo o al importar artículos mediante Importar Excel.

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
cost	Costo
price	Precio
attrs	Atributos

Ejemplo de payload – 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 vencimiento",
      "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 se no activado for ediciones masivas realizadas a través de Centro de datos > Artículo o mediante la función Importar Excel .

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
cost	Costo
price	Precio
attrs	Atributos

Ejemplo de payload – 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 vencimiento",
      "type": "date",
      "value": "2027-08-07"
    },
    {
      "id": 668272,
      "name": "Stock de seguridad",
      "type": "number",
      "value": 33
    }
  ]
}

item/delete

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

Nota: Este evento se 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 payload – Artículo eliminado

{
  "id": 26122826
}