> For the complete documentation index, see [llms.txt](https://www.boxhero.io/docs/llms.txt). Every page is available as Markdown by appending `.md` to its URL; this page is [Markdown](https://www.boxhero.io/docs/es/integrations/webhook.md).

# Webhook

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

![](https://assets.boxhero.io/docs/images/e073efd69a551d1c50313ce8969f89656fe7fb6c2f4bf97cd67eb7398f4e21d6-1601x941.jpeg)

---

## Registro

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

![](https://assets.boxhero.io/docs/images/39738e2bf18459a1ba1d9df4c6a3eb786fc434f5fab37932e8edf50bf6a0b91a-1100x810.png)

## 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:

```json
{
  "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

> **Note**
>
> Si necesita compatibilidad con otros temas de eventos, póngase en contacto con el [equipo de soporte](https://www.boxhero.io/docs/es/resources/contact).

### txs/new

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

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

| 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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

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

### item/new

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

> **Caution**
>
> **Nota**: Este evento _no_ se activa al usar la función `Agregar variantes de artículos` ni al importar artículos mediante `Importar Excel`.

| 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

```json
{
  "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.

> **Caution**
>
> **Nota**: Este evento _no_ se activa para las ediciones masivas realizadas desde `Centro de datos` > `Artículo` ni mediante la función `Importar Excel`.

| 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

```json
{
  "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.

> **Caution**
>
> **Nota**: Este evento _no_ se activa para las eliminaciones masivas realizadas desde `Centro de datos` > `Artículos`.

| Campo | Descripción |
| --- | --- |
| id | ID del artículo |

#### Ejemplo de payload – artículo eliminado

```json
{
  "id": 26122826
}
```