Webhook (keluar)

Webhook adalah sisi «push» dari integrasi: alih-alih sistem Anda menanyai FreeMaint, FreeMaint yang mengirim POST ke URL Anda begitu sesuatu terjadi. Diatur di Pengaturan perusahaan > Webhook (/company-settings/webhooks). Tersedia mulai paket Starter (100 pengiriman/hari; tanpa batas mulai Business).

Event yang tersedia

• work_order.created — sebuah perintah kerja dibuat
• work_order.completed — sebuah perintah kerja menjadi Selesai
• work_order.status_changed — sebuah perintah kerja berpindah ke status apa pun; payload membawa new_status. Dipicu bersama work_order.completed, yang tidak berubah
• request.created — sebuah permintaan pemeliharaan dikirim
• request.status_changed — sebuah permintaan disetujui, ditolak, atau dibatalkan
• part.low_stock — sebuah suku cadang turun ke titik pemesanan ulang atau di bawahnya
• part.out_of_stock — sebuah suku cadang turun ke nol
• part.low_stock_summary — satu ringkasan harian per perusahaan yang mencantumkan suku cadang pada titik pemesanan ulang atau di bawahnya, termasuk yang tidak pernah bergerak
• part.out_of_stock_summary — ringkasan harian yang sama, untuk suku cadang yang berada di nol
• part.consumed — sebuah suku cadang dipakai pada perintah kerja, atau dikembalikan
• compliance.chain_divergence — rantai hash audit terputus (Enterprise)
• asset.downtime_started — sebuah penghentian mesin dibuka
• asset.downtime_ended — sebuah penghentian mesin ditutup; durasinya kini bisa dibukukan
• report.daily_summary — pekerjaan yang selesai hari itu, sekali sehari pada jam yang Anda pilih
• purchase_order.created — pesanan pembelian dibuat; payload membawa pesanan (reference, status, total_cost, currency, expected_date, erp_reference) dan pemasoknya
• purchase_order.status_changed — status pesanan pembelian berubah (disetujui, dipesan, dibatalkan…); payload membawa previous_status dan new_status
• purchase_order.received — sebuah pengiriman diterima untuk suatu pesanan pembelian (dikirim pada setiap pengiriman, termasuk sebagian); payload mencantumkan setiap baris dengan quantity_ordered, quantity_received (pengiriman ini), quantity_received_total dan quantity_remaining, serta receipt_id, fully_received dan closed_short; new_status bernilai PARTIALLY_RECEIVED selama barang masih ditunggu dan RECEIVED setelah pesanan lengkap atau ditutup

part.consumed — mencerminkan stok ke ERP

Inilah event yang Anda langgani ketika sistem lain (ERP, penagihan, persediaan, akuntansi) harus mencerminkan apa yang benar-benar dipakai pemeliharaan. quantity bertanda: negatif saat suku cadang dikeluarkan untuk pekerjaan, positif saat dikembalikan dengan menghapusnya dari perintah kerja — sehingga pembatalan di FreeMaint menghasilkan dokumen retur yang bersesuaian di sisi sana. stock_movement_id tetap sama di seluruh percobaan ulang dan pengiriman ulang: pakai sebagai kunci idempotensi, dan pengeluaran yang sama tidak akan pernah terbukukan dua kali. Satu hal penting bila lalu lintas berjalan dua arah: mutasi GraphQL adjustStock TIDAK memicu peristiwa ini. Ini disengaja — koreksi stok yang ditulis sistem Anda sendiri ke FreeMaint tidak boleh kembali kepada Anda sebagai gema lalu dibukukan dua kali. Hanya pemakaian yang dicatat pada perintah kerja di dalam FreeMaint yang memunculkan part.consumed. Suku cadang juga membawa custom_reference: kode Anda sendiri untuknya, yaitu customReference yang diatur melalui createPart atau updatePart, sehingga sistem yang mengelola katalog dapat mencocokkan setiap baris tanpa menyimpan tabel ID FreeMaint.

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

Pengiriman dan tanda tangan

Setiap pengiriman adalah POST dengan body JSON dan header X-FreeMaint-Signature berformat t=<detik unix>,v1=<hex>, dengan v1 adalah HMAC-SHA256 dari string «<t>.<body mentah>» memakai secret webhook Anda sebagai kunci. Verifikasi terhadap body MENTAH, sebelum parsing JSON atau serialisasi ulang apa pun. Kami juga mengirim X-FreeMaint-Event dan X-FreeMaint-Delivery-Id. Respons 2xx berarti terkirim; galat jaringan dan 5xx diulang hingga 3 kali dengan backoff eksponensial (sekitar 2 dtk, 4 dtk, 8 dtk); 4xx dianggap penolakan permanen dan TIDAK diulang.

Mengirim ulang sebuah pengiriman

Setiap percobaan tersimpan di riwayat pengiriman webhook, lengkap dengan status dan kode responsnya. Pengiriman yang sudah selesai bisa dikirim ulang dari sana: payload tersimpan dikirim apa adanya, sehingga kunci bisnis di dalamnya (termasuk stock_movement_id) tetap sama dan penerima yang melakukan deduplikasi dengan benar tidak akan membukukan dua kali. Begitulah cara menyusul ketika endpoint Anda sempat mati atau keliru menolak permintaan.

Foto (opsional)

Jika "Sertakan foto" aktif pada webhook (nonaktif secara bawaan), objek "work_order" dan "request" membawa larik "photos": hingga 4 tautan HTTPS ke gambar JPG, PNG, GIF, atau WebP, yang terbaru lebih dulu. Setiap tautan membuka gambar tanpa masuk selama 7 hari, jadi simpan berkas di sistem Anda jika membutuhkannya lebih lama. Pengiriman ulang mengirim tautan yang sama. Peristiwa dan webhook lain tidak berubah. Untuk "work_order.created" dan "request.created", webhook dengan "Sertakan foto" dikirim 90 detik setelah peristiwa (kolom "timestamp" tetap memuat waktu peristiwa), agar foto yang diunggah tepat setelah catatan dibuat ikut terkirim.

Syarat URL

• Hanya https:// — http biasa ditolak
• Hanya port 443 atau 8443
• Host harus dapat dijangkau publik — rentang loopback, privat, dan CGNAT ditolak
• Tanpa kredensial di URL (https://user:pass@host ditolak)
• Sistem yang hanya ada di jaringan internal Anda memerlukan endpoint publik atau relai (n8n, Make, Zapier) di depannya

Batas

• Starter — 100 pengiriman/hari per perusahaan
• Business — tanpa batas
• Enterprise — tanpa batas
• Penghitung menghitung percobaan pengiriman: tiga webhook yang melanggan event sama memakai tiga unit
• Penghitung harian direset pukul 00:00 UTC