Webhook

Los webhooks son una función que le permite recibir notificaciones en tiempo real cuando se producen determinados eventos en BoxHero.

Registro

Puede registrar un webhook en Ajustes > Integraciones y API de su equipo de BoxHero.

Comportamiento de entrega y reintentos

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

Si su servidor responde con cualquier código de estado 2xx (por ejemplo, 200, 201, 204), la entrega se considera correcta.
Cualquier respuesta distinta de 2xx se considera un error y se volverá a intentar.

Estructura del payload del webhook

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

{
  "id": "3f9a2b7c-6d4e-4a1f-9c8b-2e5d7a0f1b34", // Event's unique ID
  "topic": "txs/new", // Event topic
  "version": 1, // Payload schema version
  "payload": { // Event-specific data
    ...
  },
  "created_time": "2025-08-06T09:20:48.623Z" // Timestamp of event occurrence (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 artículo.

El campo created_time del payload del evento representa la hora real del evento. Implemente una lógica idempotente y tolerante al orden en su controlador de webhooks para procesar los eventos de forma fiable.

Temas de eventos

txs/new

Se activa cuando se produce una transacción de inventario (Ingreso de existencias / Salida de existencias / Ajustar / Mover existencias).

Campo	Obligatorio	Descripción
id	✓	ID único de la transacción
type	✓	Tipo de transacción (in, out, adjust, move)
partner		Socio
partner.id		ID único del socio
partner.name		Nombre del socio
partner.deleted		Indica si el socio se ha 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		Indica si la ubicación de origen se ha eliminado
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	✓	Indica si la ubicación de destino se ha eliminado
items	✓	Líneas de artículos de la transacción
items.id	✓	ID único del artículo
items.name	✓	Nombre del artículo
items.quantity	✓	Cambio de inventario debido al ingreso/salida/ajuste/movimiento de existencias
items.deleted	✓	Indica si el artículo se ha eliminado
items.from_location_new_stock_level		Nivel de existencias en la ubicación de origen después de la transacción
items.to_location_new_stock_level	✓	Nivel de existencias en la ubicación de destino después de la transacción
transaction_time	✓	Hora de la transacción (p. ej., hora del ingreso o la salida de existencias)
created_at	✓	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	✓	Indica si el miembro se ha eliminado
count_of_items	✓	Número de artículos
total_quantity	✓	Cantidad total del 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 de webhook: evento Stock In

{
  "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 de webhook: evento Move Stock

{
  "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 se edita una transacción de inventario existente (Ingreso de existencias / Salida de existencias / Mover existencias / Ajustar).

Campo	Obligatorio	Descripción
id	✓	ID único de la transacción
type	✓	Tipo de transacción (in, out, adjust, move)
partner		Socio
partner.id		ID único del socio
partner.name		Nombre del socio
partner.deleted		Indica si el socio se ha 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		Indica si la ubicación de origen se ha eliminado
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	✓	Indica si la ubicación de destino se ha eliminado
items	✓	Líneas de artículos de 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 (ingreso/salida/ajuste/movimiento)
items.deleted	✓	Indica si el artículo se ha eliminado
items.from_location_new_stock_level		Nivel de existencias en la ubicación de origen después de la transacción
items.to_location_new_stock_level	✓	Nivel de existencias en la ubicación de destino después de la transacción
transaction_time	✓	Hora de la transacción (p. ej., hora del ingreso o la salida de existencias)
created_at	✓	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	✓	Indica si el miembro se ha eliminado
count_of_items	✓	Número de artículos
total_quantity	✓	Cantidad total del 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, a partir de 1

Ejemplo de payload de webhook: transacción Stock In editada

{
  "id": 16160911,
  "revision": 2,
  "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 de webhook: transacción Move Stock editada

{
  "id": 3692714,
  "revision": 2,
  "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 se elimina una transacción de inventario.

Campo	Descripción
id	ID único de la transacción
revision	Número de versión actual de la transacción, a partir de 1

Ejemplo de payload de webhook: transacción eliminada

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

item/new

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

Campo	Descripción
id	ID del artículo
name	Nombre del artículo
sku	SKU
barcode	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": "Category",
      "type": "text",
      "value": "Foundation"
    },
    {
      "id": 459264,
      "name": "Expiration date",
      "type": "date",
      "value": "2027-08-07"
    },
    {
      "id": 668272,
      "name": "Safety Stock",
      "type": "number",
      "value": 33
    }
  ]
}

item/edit

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

Campo	Descripción
id	ID del artículo
name	Nombre del artículo
sku	SKU
barcode	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": "Category",
      "type": "text",
      "value": "Foundation"
    },
    {
      "id": 459264,
      "name": "Expiration date",
      "type": "date",
      "value": "2027-08-07"
    },
    {
      "id": 668272,
      "name": "Safety Stock",
      "type": "number",
      "value": 33
    }
  ]
}

item/delete

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

Campo	Descripción
id	ID del artículo

Ejemplo de payload – artículo eliminado

{
  "id": 26122826
}