Webhook

Os webhooks são um recurso que permite receber notificações em tempo real quando determinados eventos ocorrem no BoxHero.

Cadastro

Você pode cadastrar um webhook em Configurações > Integrações e API na sua equipe do BoxHero.

Entrega e novas tentativas

Quando um evento ocorre, o BoxHero envia uma requisição HTTP POST para o endpoint de webhook cadastrado. O corpo da requisição contém um payload JSON que descreve o evento.

Se o seu servidor responder com qualquer código de status 2xx (por exemplo, 200, 201, 204), a entrega é considerada bem-sucedida.
Qualquer resposta diferente de 2xx é considerada uma falha, e o envio será tentado novamente.

Estrutura do payload do webhook

Todos os eventos de webhook são entregues com a seguinte estrutura JSON no corpo da requisição:

{
  "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)
}

Ordem dos eventos

O BoxHero não garante a ordem de entrega dos eventos. Por exemplo, um evento item/new pode chegar depois de um evento item/delete do mesmo item.

O campo created_time no payload do evento representa o horário real em que o evento ocorreu. Implemente no seu handler de webhook uma lógica idempotente e tolerante à ordem para processar os eventos de forma confiável.

Tópicos de eventos

txs/new

Acionado quando ocorre uma transação de inventário (entrada de estoque / saída de estoque / ajuste de estoque / movimentação de estoque).

Campo	Obrigatório	Descrição
id	✓	ID único da transação
type	✓	Tipo de transação (in, out, adjust, move)
partner		Parceiro
partner.id		ID único do parceiro
partner.name		Nome do parceiro
partner.deleted		Se o parceiro foi excluído
from_location		Local de origem
from_location.id		ID único do local de origem
from_location.name		Nome do local de origem
from_location.deleted		Se o local de origem foi excluído
to_location	✓	Local de destino
to_location.id	✓	ID único do local de destino
to_location.name	✓	Nome do local de destino
to_location.deleted	✓	Se o local de destino foi excluído
items	✓	Itens da transação
items.id	✓	ID único do item
items.name	✓	Nome do item
items.quantity	✓	Variação do estoque por entrada/saída/ajuste/movimentação
items.deleted	✓	Se o item foi excluído
items.from_location_new_stock_level		Nível de estoque no local de origem após a transação
items.to_location_new_stock_level	✓	Nível de estoque no local de destino após a transação
transaction_time	✓	Horário da transação (por exemplo, horário da entrada/saída de estoque)
created_at	✓	Horário em que a transação foi criada
created_by	✓	Membro que criou a transação
created_by.id	✓	ID único do membro
created_by.name	✓	Nome do membro
created_by.deleted	✓	Se o membro foi excluído
count_of_items	✓	Número de itens
total_quantity	✓	Variação total do estoque
url	✓	Endereço URL para ver a página de detalhes da transação
memo		Observações sobre a transação

Exemplo 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"
}

Exemplo 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

Enviado quando uma transação de inventário existente (entrada de estoque / saída de estoque / movimentação de estoque / ajuste de estoque) é editada.

Campo	Obrigatório	Descrição
id	✓	ID único da transação
type	✓	Tipo de transação (in, out, adjust, move)
partner		Parceiro
partner.id		ID único do parceiro
partner.name		Nome do parceiro
partner.deleted		Se o parceiro foi excluído
from_location		Local de origem
from_location.id		ID único do local de origem
from_location.name		Nome do local de origem
from_location.deleted		Se o local de origem foi excluído
to_location	✓	Local de destino
to_location.id	✓	ID único do local de destino
to_location.name	✓	Nome do local de destino
to_location.deleted	✓	Se o local de destino foi excluído
items	✓	Itens da transação
items.id	✓	ID único do item
items.name	✓	Nome do item
items.quantity	✓	Variação da quantidade pela transação (entrada/saída/ajuste/movimentação)
items.deleted	✓	Se o item foi excluído
items.from_location_new_stock_level		Nível de estoque no local de origem após a transação
items.to_location_new_stock_level	✓	Nível de estoque no local de destino após a transação
transaction_time	✓	Horário da transação (por exemplo, horário da entrada/saída de estoque)
created_at	✓	Horário em que a transação foi criada
created_by	✓	Membro que criou a transação
created_by.id	✓	ID único do membro
created_by.name	✓	Nome do membro
created_by.deleted	✓	Se o membro foi excluído
count_of_items	✓	Número de itens
total_quantity	✓	Variação total do estoque
url	✓	Endereço URL para ver a página de detalhes da transação
memo		Observações sobre a transação
revision	✓	Número da versão atual da transação, a partir de 1

Exemplo de payload de webhook – transação 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"
}

Exemplo de payload de webhook – transação 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

Enviado quando uma transação de inventário é excluída.

Campo	Descrição
id	ID único da transação
revision	Número da versão atual da transação, a partir de 1

Exemplo de payload de webhook – transação excluída

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

item/new

Enviado quando um novo item é adicionado ao inventário da equipe.

Campo	Descrição
id	ID do item
name	Nome do item
sku	SKU
barcode	Código de barras
photo_url	URL da foto
cost	Custo
price	Preço
attrs	Atributos

Exemplo de payload – item criado

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

Enviado quando um item existente é editado.

Campo	Descrição
id	ID do item
name	Nome do item
sku	SKU
barcode	Código de barras
photo_url	URL da foto
cost	Custo
price	Preço
attrs	Atributos

Exemplo de payload – item atualizado

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

Enviado quando um item é excluído do inventário da equipe.

Campo	Descrição
id	ID do item

Exemplo de payload – item excluído

{
  "id": 26122826
}