Webhooks de saída

Os webhooks fazem o FreeMaint enviar um POST para um URL que controla, assim que algo acontece, para que outro sistema (ERP, faturação, stocks, contabilidade, um canal de conversa) se mantenha alinhado sem reintroduzir dados. Configuração em /company-settings/webhooks. O Starter está limitado a 100 entregas/dia; Business e superiores são ilimitados. Para a referência completa dos payloads, veja API & GraphQL > Webhooks.

Eventos disponíveis

• work_order.created — foi criada uma ordem de trabalho
• work_order.completed — uma ordem de trabalho passou a Concluída
• work_order.status_changed — uma ordem de trabalho mudou para qualquer estado; work_order.completed continua também a ser enviado
• request.created — foi submetido um pedido de manutenção
• request.status_changed — um pedido foi aprovado, recusado ou cancelado
• part.low_stock — uma peça desceu ao ponto de encomenda ou abaixo
• part.out_of_stock — uma peça chegou a zero
• part.low_stock_summary — uma vez por dia, as peças no ponto de encomenda ou abaixo, incluindo as que nunca se movimentaram
• part.out_of_stock_summary — uma vez por dia, as peças a zero
• part.consumed — consumida numa ordem de trabalho, ou devolvida
• compliance.chain_divergence — a cadeia de hash de auditoria quebrou (Enterprise)
• asset.downtime_started — foi aberta uma paragem de máquina
• asset.downtime_ended — foi fechada uma paragem de máquina
• report.daily_summary — os trabalhos concluídos do dia, uma vez por dia à hora que escolher
• purchase_order.created — foi criada uma ordem de compra
• purchase_order.status_changed — uma ordem de compra mudou de estado (aprovada, encomendada, cancelada…)
• purchase_order.received — foi recebida uma entrega de uma ordem de compra, incluindo as entregas parciais

Semântica de entrega

• POST com corpo JSON: { event, timestamp, data }
• Cabeçalho X-FreeMaint-Signature — t=<segundos unix>,v1=<hex>, em que v1 é o HMAC-SHA256 de «<t>.<corpo em bruto>» com o segredo do seu webhook como chave. Verifique-o em cada pedido, sobre o corpo em bruto
• São também enviados X-FreeMaint-Event e X-FreeMaint-Delivery-Id
• Erros de rede e 5xx são repetidos até 3 vezes com recuo exponencial (cerca de 2 s, 4 s, 8 s); um 4xx é recusa definitiva e não é repetido
• Cada tentativa fica registada no webhook com o estado, o código de resposta e o número de tentativas — e qualquer entrega concluída pode ser reenviada a partir daí
• Fotografias opcionais: com «Incluir fotografias» ativo, os eventos "work_order" e "request" incluem até 4 ligações de imagens num campo "photos", válidas durante 7 dias para qualquer pessoa que as tenha — ative apenas para um endpoint que controle

Configuração

1. Abrir /company-settings/webhooks — Exige a permissão de definições da empresa ou a permissão «Gerir integrações».
2. Clicar em «Adicionar webhook» — Dê-lhe um nome, um URL https:// e assinale os eventos pretendidos.
3. Copiar o segredo de assinatura — É mostrado UMA única vez na criação. Depois pode gerar outro com «Rodar segredo», o que invalida o anterior.
4. Acompanhar as entregas — Abra o histórico de entregas do webhook para confirmar que os eventos chegam e reenviar o que falhou.

Limites por plano

• Starter — 100 entregas/dia por empresa (contador reposto às 00:00 UTC)
• Business — ilimitado
• Enterprise — ilimitado
• O contador conta TENTATIVAS: três webhooks no mesmo evento consomem três unidades