Webhooks

Webhooks

Os Webhooks permitem que seu Board envie requisições HTTP para serviços externos sempre que certos eventos acontecem durante a produção — uma quantidade é registrada, uma tarefa é iniciada, uma tarefa é bloqueada, um trabalho é concluído e mais. É assim que você conecta seu Board ao Slack, Microsoft Teams, um ERP, uma plataforma de notificação, um script personalizado ou qualquer outra coisa que possa receber uma requisição HTTP.

Os Webhooks vivem em Configurações do aplicativo → Webhooks.

Nota: Os Webhooks devem estar habilitados para sua conta. Se a página mostrar um aviso dizendo que os webhooks estão desabilitados, entre em contato com o suporte para ativá-los.

---

Sumário

1. O que é um webhook?
2. Quando usar webhooks
3. Criando um webhook
4. Referência de campos
5. Eventos aos quais você pode se inscrever
6. Referência de payload
7. Autenticação (chave de API)
8. Escopo de estação de trabalho
9. Testando um webhook
10. Exemplos práticos
11. Logs e solução de problemas
12. Notas de segurança

---

O que é um webhook?

Um webhook é uma URL que você fornece ao seu Board. Sempre que um evento ao qual você se inscreveu ocorre, o Board envia uma requisição HTTP POST para essa URL com um pequeno payload JSON descrevendo o que aconteceu.

O outro lado é sua escolha — uma URL de webhook de entrada do Slack, um gatilho “Catch Hook” do Zapier, um endpoint em seu próprio servidor, uma plataforma de automação, qualquer coisa que possa receber HTTP e analisar JSON.

Webhooks são unidirecionais e dispare e esqueça — o Board não espera uma resposta significativa, apenas registra o código de status para diagnósticos. Se seu endpoint estiver lento ou temporariamente fora do ar, o Board não tenta novamente automaticamente.

---

Quando usar webhooks

Alguns casos de uso reais:

• Notificações — poste uma mensagem no Slack/Teams sempre que uma tarefa for bloqueada, um trabalho for concluído ou uma tarefa de alta prioridade começar em uma estação de trabalho específica.
• Sincronização ERP / contabilidade — deixe seu sistema de back-office saber que quantidades foram fabricadas para que o inventário e o faturamento possam atualizar.
• Dashboards personalizados — alimente um Grafana externo, Looker ou dashboard caseiro com dados de produção em tempo real.
• Disparando outras automações — inicie a impressão de etiquetas de envio, instruções de embalagem ou fluxos de controle de qualidade quando um trabalho atinge um status concluído.
• Logging de auditoria / conformidade — transmita cada mudança de quantidade ou registro de tempo para um arquivo externo.

---

Criando um webhook

1. Vá para Configurações do aplicativo → Webhooks.
2. Preencha o formulário no topo da página:
   • Origem — qual origem de pedido deve disparar este webhook (ou Todas as origens).
   • URL do Webhook — a URL que seu serviço externo expõe.
   • Chave de API (opcional) — um token de autenticação (veja Autenticação).
   • Eventos — marque um ou mais eventos que você quer receber.
   • Estações de trabalho (opcional) — escolha estações de trabalho específicas para definir o escopo, ou deixe vazio para disparar para todas as estações de trabalho.
3. Clique em Adicionar (ou Atualizar se editando um webhook existente).

O novo webhook aparece na tabela abaixo. Você pode editá-lo a qualquer momento, excluí-lo ou enviar uma requisição de teste manual.

---

Referência de campos

Campo	Descrição
Origem	A origem de pedido a que o webhook se aplica. Escolha Todas as origens para receber eventos para pedidos de qualquer origem, ou escolha uma chave de origem específica (manual, shopify etc.) para disparar apenas quando o pedido do trabalho veio dessa origem.
URL do Webhook	A URL HTTPS completa para a qual o Board deve fazer POST. Máximo de 2000 caracteres.
Chave de API (opcional)	Se definida, o Board a envia em cada requisição em dois cabeçalhos — Authorization: Bearer <key> e X-API-Key: <key>. Use isto se seu endpoint requer autenticação. Deixe vazio para endpoints públicos (por exemplo, webhooks de entrada do Slack).
Eventos	Um ou mais eventos que disparam este webhook. Veja Eventos.
Estações de trabalho (opcional)	Uma lista de estações de trabalho às quais este webhook tem escopo. Vazio = dispara para todas as estações de trabalho. Veja Escopo de estação de trabalho.

---

Eventos aos quais você pode se inscrever

Cada webhook dispara apenas para eventos que você marcou. Você pode marcar quantos quiser.

qty_changed — Quantidade alterada

Dispara cada vez que uma quantidade é registrada contra uma estação de trabalho em qualquer trabalho — através do dashboard, do Kiosk, do aplicativo móvel ou da API. O payload inclui a estação de trabalho, o total fabricado até agora para o trabalho e campos identificadores sobre o trabalho e o pedido.

Exemplo de uso: alimentar um sistema ERP em tempo real com progresso de fabricação.

time_log_saved — Registro de tempo salvo

Dispara sempre que uma entrada de registro de controle de tempo é criada — seja manualmente via o botão “Submit” do Kiosk, ou quando um temporizador é parado. O payload inclui a duração em minutos, o funcionário, a estação de trabalho, qualquer nota e a quantidade (se houver) que foi registrada ao mesmo tempo.

Exemplo de uso: registrar produtividade em um sistema de faturamento/folha de pagamento.

job_blocked — Tarefa bloqueada

Dispara quando um funcionário marca uma tarefa como bloqueada (por exemplo, “material faltando”, “máquina parada”). O payload inclui a nota de bloqueio explicando o motivo.

Exemplo de uso: postar um alerta imediato no Slack para que um supervisor possa investigar.

job_completed — Tarefa concluída (trabalho inteiro)

Dispara quando um trabalho inteiro é concluído — ou seja, quando o status do trabalho transita para o status de conclusão configurado (mudado manualmente, ou automaticamente quando cada estação de trabalho atinge sua quantidade planejada). O payload inclui a duração total em minutos em todas as entradas de controle de tempo no trabalho.

Exemplo de uso: disparar um fluxo de etiqueta de envio ou faturamento uma vez que um trabalho está totalmente concluído.

task_started — Tarefa iniciada na estação de trabalho

Dispara uma vez por estação de trabalho por trabalho, a primeira vez que atividade é registrada nela. Atividade significa que a primeira quantidade > 0 é registrada, ou o primeiro temporizador de controle de tempo é iniciado nessa estação de trabalho — o que vier primeiro. O payload inclui um timestamp ISO started_at.

Exemplo de uso: notificar um supervisor que o trabalho começou em uma etapa crítica, para que saibam que a produção realmente começou.

task_completed — Tarefa concluída na estação de trabalho

Dispara uma vez por estação de trabalho por trabalho, a primeira vez que essa estação de trabalho atinge sua quantidade planejada (ou para departamentos com quantidade compartilhada, o momento em que a quantidade agrupada do departamento atende ao total do trabalho). O payload inclui um timestamp ISO completed_at.

Exemplo de uso: disparar o sistema downstream da próxima etapa (embalagem, QA, envio) no momento em que uma etapa de produção específica termina.

Idempotência para task_started / task_completed: cada um é registrado permanentemente na linha da estação de trabalho, então dispara apenas a primeira vez que a condição é atendida. Registrar mais quantidade ou reiniciar um temporizador após o primeiro acerto não redispara esses eventos.

---

Referência de payload

Cada evento envia um objeto JSON via HTTP POST. Alguns campos são comuns a todos os eventos; outros são específicos ao tipo de evento. Campos vazios/null são omitidos para manter os payloads compactos.

Campos base (presentes para todos os eventos)

{
    "event": "qty_changed",
    "job_ref": "PB-0042",
    "order_ref": "PO-2025-001",
    "order_external_id": "EXT-12345",
    "manufactured_qty": 7,
    "sku": "TABLE-OAK-90",
    "name": "Oak Coffee Table",
    "external_id": "ORD-7890",
    "department": "Assembly",
    "workstation": "Station A",
    "workstation_id": 12
}

Campo	Significado
event	A chave do evento — uma das seis listadas acima.
job_ref	O número de referência do trabalho em seu Board.
order_ref	A referência do pedido pai, se houver.
order_external_id	O ID externo do pedido (por exemplo, um ID de pedido Shopify).
manufactured_qty	Quantidade total fabricada para este trabalho em todas as estações de trabalho. (Para time_log_saved, este é o total da estação de trabalho, não do trabalho.)
sku	O SKU do trabalho.
name	O nome do trabalho.
external_id	O ID externo do trabalho (por exemplo, o identificador do sistema upstream).
department	Departamento da estação de trabalho envolvida, se uma estação de trabalho está no contexto.
workstation	Nome da estação de trabalho envolvida.
workstation_id	ID numérico da estação de trabalho envolvida.

Os campos department, workstation e workstation_id estão presentes sempre que o evento se relaciona a uma estação de trabalho específica (então todos os eventos exceto job_completed, que é de trabalho inteiro).

Extras por evento

Evento	Campos extras
qty_changed	—
time_log_saved	mode ("manual" ou "work_stopped"), log_qty, log_note, duration_minutes, employee (objeto com id, name, surname)
job_blocked	block_note
job_completed	status (nome do status de conclusão), total_duration_minutes
task_started	started_at (timestamp ISO 8601)
task_completed	completed_at (timestamp ISO 8601)

Exemplo: payload de task_started

{
    "event": "task_started",
    "job_ref": "PB-0042",
    "order_ref": "PO-2025-001",
    "manufactured_qty": 0,
    "sku": "TABLE-OAK-90",
    "name": "Oak Coffee Table",
    "department": "Assembly",
    "workstation": "Station A",
    "workstation_id": 12,
    "started_at": "2026-05-27T08:14:32+00:00"
}

Exemplo: payload de time_log_saved

{
    "event": "time_log_saved",
    "job_ref": "PB-0042",
    "manufactured_qty": 5,
    "sku": "TABLE-OAK-90",
    "name": "Oak Coffee Table",
    "department": "Assembly",
    "workstation": "Station A",
    "workstation_id": 12,
    "mode": "work_stopped",
    "log_qty": 2,
    "log_note": "Two units finished, third in progress",
    "duration_minutes": 47,
    "employee": { "id": 8, "name": "Jan", "surname": "Kowalski" }
}

---

Autenticação (chave de API)

Se seu endpoint requer autenticação, preencha o campo Chave de API. O Board a envia em cada requisição em dois cabeçalhos:

Authorization: Bearer <your-api-key>
X-API-Key: <your-api-key>

A maioria dos endpoints aceita qualquer uma das formas, então não importa qual você verifica do lado receptor.

Deixe Chave de API vazia para endpoints públicos como webhooks de entrada do Slack — eles não esperam nenhum cabeçalho de autenticação.

---

Escopo de estação de trabalho

Por padrão, um webhook dispara para cada estação de trabalho. O campo opcional Estações de trabalho permite restringi-lo.

Lista vazia (padrão)

O webhook dispara para todas as estações de trabalho. Este é o comportamento original — webhooks existentes criados antes deste recurso não são afetados.

Estações de trabalho específicas

O webhook dispara apenas quando a estação de trabalho do evento está na lista. Útil quando:

• Você quer que um canal do Slack receba alertas apenas para as estações de trabalho da equipe de pintura.
• Você quer uma integração ERP que só se importa com estações de trabalho de montagem final.
• Equipes diferentes devem receber notificações diferentes.

Comportamento com eventos sem estação de trabalho

O evento job_completed é disparado no nível de trabalho inteiro (sem estação de trabalho específica). Um webhook com uma ou mais estações de trabalho selecionadas não disparará para job_completed — por design. Se você quer um webhook para receber job_completed, deixe a lista de estações de trabalho vazia (ou crie um segundo webhook apenas para esse evento).

Combinado com Origem

O filtro de estação de trabalho é aplicado em cima do filtro de origem. Um webhook com source=shopify e estações de trabalho [A, B] só dispara quando o evento combina com ambos — um evento de trabalho de origem Shopify acontecendo na estação de trabalho A ou B.

---

Testando um webhook

A tabela de webhooks tem um ícone de avião de papel (✈) ao lado de cada linha — clique nele para abrir o diálogo de teste.

1. Escolha um evento dos eventos inscritos do seu webhook.
2. Um payload de amostra é renderizado como JSON. Edite-o livremente — mude qualquer campo para simular um cenário real.
3. Clique em Enviar teste. O diálogo muda para um painel de resultado mostrando:
   • Código de status HTTP retornado pelo seu endpoint
   • Tempo gasto (em milissegundos)
   • Corpo da resposta (truncado a 2 KB)
   • Qualquer erro de conexão
4. Clique em Voltar para editar para ajustar o payload e tentar novamente.

Esta é a maneira mais rápida de verificar se seu endpoint é alcançável, analisa o payload corretamente e responde com um status 2xx.

---

Exemplos práticos

1. Alerta do Slack quando qualquer tarefa é bloqueada

• Origem: Todas as origens
• URL: uma URL de webhook de entrada do Slack
• Chave de API: vazia
• Eventos: apenas job_blocked
• Estações de trabalho: vazias

No Slack, o payload chega como JSON; você pode formatá-lo bem com um relay (por exemplo, um Cloudflare Worker que transforma block_note + workstation em uma mensagem do Slack). Ou use um serviço como Zapier entre os dois para fazer a formatação.

2. E-mail para um supervisor quando a pintura termina um trabalho

• Origem: Todas as origens
• URL: uma URL “Catch Hook” do Zapier conectada a uma etapa “Send Email” do Gmail
• Eventos: task_completed
• Estações de trabalho: marque todas as estações de trabalho de pintura

O webhook dispara no momento em que a porção da pintura de qualquer trabalho está pronta. O Zapier formata o e-mail a partir dos campos do payload.

3. Enviar quantidades fabricadas para um ERP

• Origem: uma origem externa específica (por exemplo, shopify)
• URL: o endpoint de entrada do seu ERP
• Chave de API: o token de API do ERP
• Eventos: qty_changed, job_completed
• Estações de trabalho: vazias (você quer todas)

O ERP recebe um payload após cada mudança de quantidade mais um aviso final de trabalho inteiro quando o trabalho está totalmente completo.

4. Notificações diferentes por departamento

Crie três webhooks separados, cada um com escopo nas estações de trabalho de seu próprio departamento:

• “Slack Montagem” → task_started, task_completed, job_blocked, estações de trabalho = apenas estações de montagem
• “Slack Pintura” → mesmos eventos, estações de trabalho = apenas estações de pintura
• “Slack Embalagem” → mesmos eventos, estações de trabalho = apenas estações de embalagem

Cada equipe vê apenas alertas que importam para eles.

---

Logs e solução de problemas

Cada requisição de webhook — eventos reais e testes manuais — é anexada a um log por inquilino no servidor em:

storage/logs/webhooks/webhook_tennent_id_<tenant_id>.log

Cada linha é um objeto JSON com o timestamp, evento, URL, status HTTP, duração, payload, corpo da resposta e qualquer erro. Este é o primeiro lugar para olhar quando um webhook parece não estar entregando.

Problemas comuns

• Endpoint retorna 4xx / 5xx — verifique o corpo da resposta no log. O Board só para de enviar no próximo evento se a URL for removida; não tenta novamente o evento atual automaticamente.
• Sem linha de log para um evento — seu webhook não está correspondendo. Verifique os filtros de origem, eventos e estações de trabalho. O diálogo Teste contorna esses filtros e é a maneira mais rápida de confirmar que a URL funciona.
• Endpoint lento — o timeout de requisição do Board é de 10 segundos. Se seu endpoint leva mais tempo, a conexão cai e um erro é registrado.
• Erros de HTTPS — certifique-se de que seu endpoint tem um certificado válido. O Board não permite certificados auto-assinados.
• Flag de inquilino desabilitada — a página mostra um aviso desabilitado se os webhooks estão desligados para sua conta. Entre em contato com o suporte.

---

Notas de segurança

• A própria URL é a credencial quando nenhuma chave de API está definida. Qualquer um que conhece a URL de um webhook não autenticado (por exemplo, um webhook de entrada do Slack) pode postar nele. Trate URLs não autenticadas como segredos e não as compartilhe publicamente.
• Use o campo Chave de API sempre que seu endpoint suportar autenticação. É uma melhoria gratuita em segurança — o Board a envia com cada requisição.
• HTTPS é necessário para qualquer endpoint que lida com dados reais de produção. O campo de URL do webhook aceita http:// também, mas use apenas para desenvolvimento local.
• Payloads incluem informações identificáveis de pedido/cliente. Certifique-se de que o serviço receptor é aprovado para manipular esses dados — especialmente para origens externas, plataformas de automação de terceiros e qualquer serviço que armazena ou registra os payloads.
• Webhooks são por inquilino. Eventos dos dados de um inquilino nunca podem alcançar os webhooks de outro inquilino.