Webhooks de saída

Os webhooks fazem o FreeMaint enviar um POST para uma URL que você controla assim que algo acontece, de modo que outro sistema (ERP, faturamento, estoque, contabilidade, um canal de chat) fique alinhado sem ninguém redigitar nada. Configure em /company-settings/webhooks. O Starter é limitado a 100 entregas/dia; Business e acima são ilimitados. Para a referência completa dos payloads, veja API & GraphQL > Webhooks.

Eventos disponíveis

• work_order.created — uma ordem de serviço foi criada
• work_order.completed — uma ordem de serviço passou para Concluída
• work_order.status_changed — uma ordem de serviço mudou para qualquer status; work_order.completed continua sendo disparado também
• request.created — uma solicitação de manutenção foi enviada
• request.status_changed — uma solicitação foi aprovada, recusada ou cancelada
• part.low_stock — uma peça chegou ao ponto de ressuprimento ou abaixo dele
• part.out_of_stock — uma peça chegou a zero
• part.low_stock_summary — uma vez por dia, as peças no ponto de ressuprimento ou abaixo, inclusive as que nunca se movimentaram
• part.out_of_stock_summary — uma vez por dia, as peças zeradas
• part.consumed — consumida em uma ordem de serviço, ou devolvida
• compliance.chain_divergence — a cadeia de hash de auditoria foi rompida (Enterprise)
• asset.downtime_started — uma parada de máquina foi aberta
• asset.downtime_ended — uma parada de máquina foi encerrada
• report.daily_summary — os trabalhos concluídos do dia, uma vez por dia no horário que você escolher
• purchase_order.created — um pedido de compra foi criado
• purchase_order.status_changed — um pedido de compra mudou de status (aprovado, pedido, cancelado…)
• purchase_order.received — uma entrega foi recebida em um pedido de compra, inclusive as parciais

Semântica de entrega

• POST com corpo JSON: { event, timestamp, data }
• Cabeçalho X-FreeMaint-Signature — t=<segundos unix>,v1=<hex>, onde v1 é o HMAC-SHA256 de «<t>.<corpo bruto>» usando o segredo do seu webhook como chave. Verifique em toda requisição, sobre o corpo bruto
• Também enviamos X-FreeMaint-Event e X-FreeMaint-Delivery-Id
• Erros de rede e 5xx são repetidos até 3 vezes com backoff exponencial (cerca de 2 s, 4 s, 8 s); um 4xx é recusa permanente e não é repetido
• Cada tentativa fica registrada no webhook com status, código de resposta e contagem de tentativas — e qualquer entrega finalizada pode ser reenviada de lá
• Fotos opcionais: com "Incluir fotos" ativado, os eventos "work_order" e "request" trazem até 4 links de imagens em um campo "photos", válidos por 7 dias para qualquer pessoa que os tenha — ative apenas para um endpoint que você controla

Configuração

1. Abrir /company-settings/webhooks — Exige a permissão de configurações da empresa ou a permissão "Gerenciar integrações".
2. Clicar em «Adicionar webhook» — Dê um nome, uma URL https:// e marque os eventos desejados.
3. Copiar o segredo de assinatura — É exibido UMA única vez na criação. Depois você pode gerar outro em «Rotacionar 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 zerado às 00:00 UTC)
• Business — ilimitado
• Enterprise — ilimitado
• O contador conta TENTATIVAS: três webhooks no mesmo evento consomem três unidades