Webhook in uscita

I webhook fanno sì che FreeMaint invii una POST a un URL che controlli tu non appena accade qualcosa, così un altro sistema (ERP, fatturazione, magazzino, contabilità, un canale di chat) resta allineato senza reinserimenti manuali. Configurazione in /company-settings/webhooks. Starter è limitato a 100 consegne/giorno; Business e superiori sono illimitati. Per il riferimento completo dei payload vedi API & GraphQL > Webhook.

Eventi disponibili

• work_order.created — è stato creato un ordine di lavoro
• work_order.completed — un ordine di lavoro è passato a Completato
• work_order.status_changed — un ordine di lavoro è passato a un qualsiasi stato; work_order.completed viene comunque inviato
• request.created — è stata inviata una richiesta di manutenzione
• request.status_changed — una richiesta è stata approvata, respinta o annullata
• part.low_stock — un ricambio è sceso al punto di riordino o sotto
• part.out_of_stock — un ricambio è sceso a zero
• part.low_stock_summary — una volta al giorno, i ricambi al punto di riordino o sotto, compresi quelli mai movimentati
• part.out_of_stock_summary — una volta al giorno, i ricambi a zero
• part.consumed — consumato su un ordine di lavoro, o reso
• compliance.chain_divergence — la catena di hash di audit si è interrotta (Enterprise)
• asset.downtime_started — è stato aperto un fermo macchina
• asset.downtime_ended — è stato chiuso un fermo macchina
• report.daily_summary — i lavori completati della giornata, una volta al giorno all'ora che scegli
• purchase_order.created — è stato creato un ordine d'acquisto
• purchase_order.status_changed — un ordine d'acquisto è passato a un altro stato (approvato, ordinato, annullato…)
• purchase_order.received — è stata ricevuta una consegna su un ordine d'acquisto, comprese quelle parziali

Semantica di consegna

• POST con corpo JSON: { event, timestamp, data }
• Header X-FreeMaint-Signature — t=<secondi unix>,v1=<hex>, dove v1 è l'HMAC-SHA256 di «<t>.<corpo grezzo>» con il segreto del webhook come chiave. Verificalo a ogni richiesta, sul corpo grezzo
• Vengono inviati anche X-FreeMaint-Event e X-FreeMaint-Delivery-Id
• Errori di rete e 5xx vengono ritentati fino a 3 volte con backoff esponenziale (circa 2 s, 4 s, 8 s); un 4xx è un rifiuto definitivo e non viene ritentato
• Ogni tentativo è registrato sotto il webhook con stato, codice di risposta e numero di tentativi — e ogni consegna conclusa può essere rinviata da lì
• Foto facoltative: con «Includi foto» attivo, gli eventi "work_order" e "request" contengono fino a 4 link a immagini nel campo "photos", validi 7 giorni per chiunque li possieda; attivalo solo per un endpoint che controlli

Configurazione

1. Apri /company-settings/webhooks — Richiede il permesso sulle impostazioni aziendali o il permesso «Gestire le integrazioni».
2. Clicca «Aggiungi webhook» — Dagli un nome, un URL https:// e spunta gli eventi desiderati.
3. Copia il segreto di firma — Viene mostrato UNA sola volta alla creazione. Più tardi puoi generarne uno nuovo con «Ruota segreto», che invalida il precedente.
4. Controlla le consegne — Apri lo storico consegne del webhook per confermare l'arrivo degli eventi e rinviare ciò che è fallito.

Limiti per piano

• Starter — 100 consegne/giorno per azienda (contatore azzerato alle 00:00 UTC)
• Business — illimitato
• Enterprise — illimitato
• Il contatore conta i TENTATIVI: tre webhook sullo stesso evento consumano tre unità