Webhook (keluar)

Webhook ialah bahagian «tolak» bagi integrasi: bukannya sistem anda menyoal FreeMaint, FreeMaint yang menghantar POST ke URL anda sebaik sahaja sesuatu berlaku. Sediakan di Tetapan syarikat > Webhook (/company-settings/webhooks). Tersedia dari pelan Starter (100 penghantaran/hari; tanpa had dari Business).

Peristiwa yang tersedia

• work_order.created — perintah kerja telah dicipta
• work_order.completed — perintah kerja bertukar kepada Selesai
• work_order.status_changed — sesuatu perintah kerja bertukar ke mana-mana status; muatan membawa new_status. Dipicu bersama work_order.completed, yang kekal tidak berubah
• request.created — permintaan penyelenggaraan telah dihantar
• request.status_changed — permintaan diluluskan, ditolak atau dibatalkan
• part.low_stock — alat ganti jatuh ke titik pesanan semula atau ke bawah
• part.out_of_stock — alat ganti jatuh ke sifar
• part.low_stock_summary — satu ringkasan harian bagi setiap syarikat yang menyenaraikan alat ganti pada titik pesanan semula atau ke bawah, termasuk yang tidak pernah bergerak
• part.out_of_stock_summary — ringkasan harian yang sama, untuk alat ganti yang berada pada sifar
• part.consumed — alat ganti digunakan pada perintah kerja, atau dipulangkan
• compliance.chain_divergence — rantaian cincang audit terputus (Enterprise)
• asset.downtime_started — satu pemberhentian mesin telah dibuka
• asset.downtime_ended — satu pemberhentian mesin telah ditutup; tempohnya kini boleh dikira
• report.daily_summary — kerja yang selesai pada hari itu, sekali sehari pada jam pilihan anda
• purchase_order.created — pesanan belian dicipta; muatan membawa pesanan (reference, status, total_cost, currency, expected_date, erp_reference) dan pembekalnya
• purchase_order.status_changed — status pesanan belian berubah (diluluskan, dipesan, dibatalkan…); muatan membawa previous_status dan new_status
• purchase_order.received — satu penghantaran telah diterima bagi pesanan pembelian (dihantar untuk setiap penghantaran, termasuk sebahagian); payload menyenaraikan setiap baris dengan quantity_ordered, quantity_received (penghantaran ini), quantity_received_total dan quantity_remaining, serta receipt_id, fully_received dan closed_short; new_status ialah PARTIALLY_RECEIVED selagi barangan masih dijangka dan RECEIVED apabila pesanan lengkap atau ditutup

part.consumed — mencerminkan stok ke ERP

Inilah peristiwa untuk dilanggan apabila sistem lain (ERP, pengebilan, inventori, perakaunan) perlu mencerminkan apa yang benar-benar digunakan oleh penyelenggaraan. quantity bertanda: negatif apabila alat ganti dikeluarkan untuk kerja, positif apabila dipulangkan dengan mengeluarkannya daripada perintah kerja — jadi pembalikan dalam FreeMaint menghasilkan dokumen pemulangan yang sepadan di sebelah sana. stock_movement_id kekal sama merentas cubaan semula dan penghantaran semula: gunakannya sebagai kunci idempoten, dan pengeluaran yang sama tidak akan sekali-kali dipos dua kali. Satu perkara yang perlu diketahui apabila trafik berjalan dua hala: mutasi GraphQL adjustStock TIDAK mencetuskan peristiwa ini. Ini disengajakan — pembetulan stok yang ditulis oleh sistem anda sendiri ke dalam FreeMaint tidak sepatutnya kembali kepada anda sebagai gema lalu dikira dua kali. Hanya penggunaan yang direkodkan pada perintah kerja di dalam FreeMaint yang menghasilkan part.consumed. Alat ganti juga membawa custom_reference: kod anda sendiri untuknya, iaitu customReference yang ditetapkan melalui createPart atau updatePart, supaya sistem yang mengurus katalog dapat memadankan setiap baris tanpa menyimpan jadual ID FreeMaint.

{ "event": "part.consumed", "timestamp": "2026-08-19T21:04:11.000Z", "data": { "part": { "id": 812, "name": "Galas 6204", "part_number": "RLM-204", "reference": "PART-812", "custom_reference": "BC-10045", "unit_cost": 12.5, "unit_of_measure": "unit" }, "quantity": -2, "previous_quantity": 48, "new_quantity": 46, "work_order": { "id": 5521, "reference": "WO-2026-0412", "title": "Penggantian galas" }, "asset": { "id": 91, "name": "Pemisah 2" }, "location": { "id": 7, "name": "Gudang kilang" }, "user": { "id": 5627, "name": "A. Juruteknik" }, "stock_movement_id": 88213, "occurred_at": "2026-08-19T21:04:11.000Z" } }

Penghantaran dan tandatangan

Setiap penghantaran ialah POST dengan badan JSON dan pengepala X-FreeMaint-Signature berformat t=<saat unix>,v1=<heks>, dengan v1 ialah HMAC-SHA256 bagi rentetan «<t>.<badan mentah>» menggunakan rahsia webhook anda sebagai kunci. Sahkan terhadap badan MENTAH, sebelum sebarang penghuraian JSON atau penyirian semula. Kami turut menghantar X-FreeMaint-Event dan X-FreeMaint-Delivery-Id. Respons 2xx bermakna berjaya dihantar; ralat rangkaian dan 5xx dicuba semula sehingga 3 kali dengan undur eksponen (kira-kira 2 s, 4 s, 8 s); 4xx dianggap penolakan kekal dan TIDAK dicuba semula.

Menghantar semula sesuatu penghantaran

Setiap cubaan disimpan dalam sejarah penghantaran webhook, bersama status dan kod responsnya. Mana-mana penghantaran yang telah selesai boleh dihantar semula dari situ: muatan tersimpan dihantar semula tanpa diubah, jadi kunci perniagaan di dalamnya (termasuk stock_movement_id) kekal sama dan penerima yang menyahduplikasi dengan betul tidak akan mengepos dua kali. Begitulah cara memulihkan apabila titik akhir anda terputus atau tersilap menolak permintaan.

Gambar (pilihan)

Apabila "Sertakan gambar" dihidupkan pada webhook (dimatikan secara lalai), objek "work_order" dan "request" membawa tatasusunan "photos": sehingga 4 pautan HTTPS ke imej JPG, PNG, GIF atau WebP, yang terkini dahulu. Setiap pautan membuka imej tanpa log masuk selama 7 hari, jadi simpan fail di pihak anda jika anda memerlukannya lebih lama. Penghantaran semula menghantar pautan yang sama. Acara dan webhook lain tidak berubah. Bagi "work_order.created" dan "request.created", webhook dengan "Sertakan gambar" dihantar 90 saat selepas acara (medan "timestamp" mengekalkan masa acara), supaya gambar yang dimuat naik sejurus selepas rekod turut disertakan.

Syarat URL

• https:// sahaja — http biasa ditolak
• Port 443 atau 8443 sahaja
• Hos mesti boleh dicapai secara awam — julat loopback, persendirian dan CGNAT ditolak
• Tiada kelayakan dalam URL (https://user:pass@host ditolak)
• Sistem yang hanya wujud dalam rangkaian dalaman anda memerlukan titik akhir awam atau geganti (n8n, Make, Zapier) di hadapannya

Had

• Starter — 100 penghantaran/hari bagi setiap syarikat
• Business — tanpa had
• Enterprise — tanpa had
• Pengira mengira cubaan penghantaran: tiga webhook yang melanggan peristiwa sama menggunakan tiga unit
• Pengira harian ditetapkan semula pada 00:00 UTC