Webhook'lar (giden)

Webhook'lar entegrasyonların «push» tarafıdır: sisteminiz FreeMaint'i sorgulamak yerine, bir şey olur olmaz FreeMaint sizin URL'nize POST gönderir. Şirket Ayarları > Webhook'lar (/company-settings/webhooks) altından kurulur. Starter paketinden itibaren kullanılabilir (günde 100 teslimat; Business ve üzerinde sınırsız).

Kullanılabilir olaylar

• work_order.created — bir iş emri oluşturuldu
• work_order.completed — bir iş emri Tamamlandı durumuna geçti
• work_order.status_changed — bir iş emri herhangi bir duruma geçti; yük new_status taşır. Değişmeden kalan work_order.completed'a ek olarak tetiklenir
• request.created — bir bakım talebi gönderildi
• request.status_changed — bir talep onaylandı, reddedildi veya iptal edildi
• part.low_stock — bir yedek parça yeniden sipariş noktasına düştü ya da altına indi
• part.out_of_stock — bir yedek parça sıfıra düştü
• part.low_stock_summary — şirket başına günde bir özet; yeniden sipariş noktasında veya altında olan yedek parçaları, hiç hareket görmemiş olanlar dâhil listeler
• part.out_of_stock_summary — sıfırda duran yedek parçalar için aynı günlük özet
• part.consumed — bir yedek parça iş emrinde tüketildi veya iade edildi
• compliance.chain_divergence — denetim hash zinciri koptu (Enterprise)
• asset.downtime_started — bir makine duruşu açıldı
• asset.downtime_ended — bir makine duruşu kapatıldı; süre artık işlenebilir
• report.daily_summary — günün tamamlanan işleri, seçtiğiniz saatte günde bir kez
• purchase_order.created — bir satın alma siparişi oluşturuldu; yük, siparişi (reference, status, total_cost, currency, expected_date, erp_reference) ve tedarikçisini taşır
• purchase_order.status_changed — bir satın alma siparişinin durumu değişti (onaylandı, sipariş verildi, iptal edildi…); yük previous_status ve new_status taşır
• purchase_order.received — bir satın alma siparişine ait bir teslimat teslim alındı (kısmi olanlar dahil her teslimatta gönderilir); yük her satırı quantity_ordered, quantity_received (bu teslimat), quantity_received_total ve quantity_remaining ile, ayrıca receipt_id, fully_received ve closed_short ile listeler; mal beklenmeye devam ettiği sürece new_status PARTIALLY_RECEIVED, sipariş tamamlandığında veya kapatıldığında RECEIVED olur

part.consumed — stoğu bir ERP'ye yansıtmak

Başka bir sistemin (ERP, faturalama, stok, muhasebe) bakımın gerçekte ne tükettiğini yansıtması gerektiğinde abone olunacak olay budur. quantity işaretlidir: parça işe çıkarken negatif, iş emrinden çıkarılarak iade edilirken pozitif — böylece FreeMaint'teki bir ters kayıt, karşı tarafta eşleşen bir iade belgesi üretir. stock_movement_id yeniden denemeler ve yeniden gönderimler boyunca sabittir: onu idempotency anahtarı olarak kullanın, aynı çıkışı asla iki kez işlemezsiniz. Trafik iki yönlü aktığında bilinmesi gereken bir nokta: GraphQL adjustStock mutasyonu bu olayı TETİKLEMEZ. Bu bilinçlidir — kendi sisteminizin FreeMaint'e yazdığı bir stok düzeltmesi, size yankı olarak geri dönüp iki kez işlenmemelidir. part.consumed yalnızca FreeMaint içinde bir iş emrine kaydedilen tüketimden doğar. Parça ayrıca custom_reference taşır: parça için kendi kodunuz, yani createPart veya updatePart ile belirlenen customReference; böylece kataloğu yöneten sistem, FreeMaint kimliklerinin tablosunu tutmadan her satırı eşleştirebilir.

{ "event": "part.consumed", "timestamp": "2026-08-19T21:04:11.000Z", "data": { "part": { "id": 812, "name": "Rulman 6204", "part_number": "RLM-204", "reference": "PART-812", "custom_reference": "BC-10045", "unit_cost": 12.5, "unit_of_measure": "ad" }, "quantity": -2, "previous_quantity": 48, "new_quantity": 46, "work_order": { "id": 5521, "reference": "WO-2026-0412", "title": "Rulman değişimi" }, "asset": { "id": 91, "name": "Separatör 2" }, "location": { "id": 7, "name": "Fabrika deposu" }, "user": { "id": 5627, "name": "A. Teknisyen" }, "stock_movement_id": 88213, "occurred_at": "2026-08-19T21:04:11.000Z" } }

Teslimat ve imza

Her teslimat, JSON gövdeli bir POST ve t=<unix saniye>,v1=<hex> biçiminde bir X-FreeMaint-Signature başlığı içerir; burada v1, webhook gizli anahtarınızla «<t>.<ham gövde>» dizesinin HMAC-SHA256'sıdır. HAM gövde üzerinden, herhangi bir JSON ayrıştırma veya yeniden serileştirmeden önce doğrulayın. Ayrıca X-FreeMaint-Event ve X-FreeMaint-Delivery-Id gönderiyoruz. 2xx yanıtı teslim edilmiş sayılır; ağ hataları ve 5xx yanıtları üstel geri çekilmeyle en fazla 3 kez yeniden denenir (yaklaşık 2 sn, 4 sn, 8 sn); 4xx kalıcı ret sayılır ve yeniden DENENMEZ.

Bir teslimatı yeniden gönderme

Her deneme, durumu ve yanıt koduyla birlikte webhook'un teslimat geçmişinde tutulur. Sonuçlanmış her teslimat oradan yeniden gönderilebilir: saklanan yük değiştirilmeden yeniden gider, dolayısıyla içindeki iş anahtarları (stock_movement_id dahil) aynı kalır ve doğru şekilde yinelenenleri ayıklayan bir alıcı çift kayıt atmaz. Uç noktanız kapalıyken ya da bir isteği yanlışlıkla reddettiğinde kaybı böyle telafi edersiniz.

Fotoğraflar (isteğe bağlı)

Bir webhook için "Fotoğrafları ekle" açık olduğunda (varsayılan olarak kapalı), "work_order" ve "request" nesneleri bir "photos" dizisi taşır: JPG, PNG, GIF veya WebP görsellerine en fazla 4 HTTPS bağlantısı, en yeniler önce. Her bağlantı görseli 7 gün boyunca oturum açmadan açar; daha uzun süre gerekiyorsa dosyayı kendi tarafınızda saklayın. Yeniden gönderim aynı bağlantıları gönderir. Diğer olaylar ve diğer webhook'lar değişmez. "work_order.created" ve "request.created" için "Fotoğrafları ekle" açık olan bir webhook, kayıttan hemen sonra yüklenen fotoğrafları içermesi için olaydan 90 saniye sonra gönderilir ("timestamp" alanı olayın zamanını korur).

URL gereksinimleri

• Yalnızca https:// — düz http reddedilir
• Yalnızca 443 veya 8443 portu
• Host herkese açık erişilebilir olmalı — loopback, özel ve CGNAT aralıkları reddedilir
• URL içinde kimlik bilgisi olmamalı (https://user:pass@host reddedilir)
• Yalnızca kendi ağınızda var olan bir sistem için önüne genel bir uç nokta ya da bir aktarıcı (n8n, Make, Zapier) gerekir

Sınırlar

• Starter — şirket başına günde 100 teslimat
• Business — sınırsız
• Enterprise — sınırsız
• Sayaç teslimat denemelerini sayar: aynı olaya abone üç webhook üç birim harcar
• Günlük sayaç 00:00 UTC'de sıfırlanır