Ausgehende Webhooks

Webhooks lassen FreeMaint ein POST an eine von Ihnen kontrollierte URL senden, sobald etwas passiert, damit ein anderes System (ERP, Fakturierung, Lager, Buchhaltung, ein Chat-Kanal) mitläuft, ohne dass jemand Daten erneut eintippt. Konfiguration unter /company-settings/webhooks. Starter ist auf 100 Zustellungen/Tag begrenzt; Business und höher sind unbegrenzt. Die vollständige Payload-Referenz steht unter API & GraphQL > Webhooks.

Verfügbare Ereignisse

• work_order.created — ein Arbeitsauftrag wurde erstellt
• work_order.completed — ein Arbeitsauftrag wurde auf Abgeschlossen gesetzt
• work_order.status_changed — ein Arbeitsauftrag hat in einen beliebigen Status gewechselt; work_order.completed wird weiterhin ebenfalls ausgelöst
• request.created — eine Wartungsanfrage wurde eingereicht
• request.status_changed — eine Anfrage wurde genehmigt, abgelehnt oder storniert
• part.low_stock — ein Ersatzteil hat seinen Meldebestand erreicht oder unterschritten
• part.out_of_stock — ein Ersatzteil ist auf null gefallen
• part.low_stock_summary — einmal täglich die Ersatzteile auf oder unter ihrem Meldebestand, einschließlich nie bewegter Teile
• part.out_of_stock_summary — einmal täglich die Ersatzteile mit Bestand null
• part.consumed — auf einem Arbeitsauftrag verbraucht oder davon zurückgegeben
• compliance.chain_divergence — die Audit-Hashkette ist gebrochen (Enterprise)
• asset.downtime_started — ein Maschinenstillstand wurde eröffnet
• asset.downtime_ended — ein Maschinenstillstand wurde beendet
• report.daily_summary — die abgeschlossenen Arbeiten des Tages, einmal täglich zur von Ihnen gewählten Uhrzeit
• purchase_order.created — eine Bestellung wurde angelegt
• purchase_order.status_changed — eine Bestellung hat den Status gewechselt (genehmigt, bestellt, storniert …)
• purchase_order.received — zu einer Bestellung wurde eine Lieferung empfangen, Teillieferungen eingeschlossen

Zustellsemantik

• POST mit JSON-Body: { event, timestamp, data }
• Header X-FreeMaint-Signature — t=<Unix-Sekunden>,v1=<hex>, wobei v1 der HMAC-SHA256 von "<t>.<Rohbody>" mit Ihrem Webhook-Secret als Schlüssel ist. Prüfen Sie ihn bei jeder Anfrage gegen den rohen Body
• X-FreeMaint-Event und X-FreeMaint-Delivery-Id werden mitgesendet
• Netzwerkfehler und 5xx werden bis zu 3-mal mit exponentiellem Backoff wiederholt (etwa 2 s, 4 s, 8 s); ein 4xx ist eine endgültige Ablehnung und wird nicht wiederholt
• Jeder Versuch wird beim Webhook mit Status, Antwortcode und Versuchszähler protokolliert — und jede abgeschlossene Zustellung kann von dort erneut gesendet werden
• Optionale Fotos: Mit „Fotos einschließen“ enthalten "work_order"- und "request"-Ereignisse bis zu 4 Bildlinks im Feld "photos", 7 Tage lang gültig für jeden, der sie besitzt – nur für einen Endpunkt aktivieren, den Sie selbst kontrollieren

Konfiguration

1. /company-settings/webhooks öffnen — Erfordert die Berechtigung für Unternehmenseinstellungen oder die Berechtigung „Integrationen verwalten“.
2. Auf "Webhook hinzufügen" klicken — Namen und https://-URL angeben und die gewünschten Ereignisse anhaken.
3. Signatur-Secret kopieren — Es wird bei der Erstellung nur EINMAL angezeigt. Später erzeugen Sie über "Secret rotieren" ein neues, wodurch das alte ungültig wird.
4. Zustellungen beobachten — Öffnen Sie den Zustellverlauf des Webhooks, um den Eingang der Ereignisse zu prüfen und Fehlgeschlagenes erneut zu senden.

Grenzwerte je Tarif

• Starter — 100 Zustellungen/Tag pro Unternehmen (Zähler wird um 00:00 UTC zurückgesetzt)
• Business — unbegrenzt
• Enterprise — unbegrenzt
• Gezählt werden ZUSTELLVERSUCHE: drei Webhooks auf dasselbe Ereignis verbrauchen drei Einheiten