Webhooki (wychodzące)

Webhooki to «push»owa połowa integracji: zamiast odpytywać FreeMaint, to FreeMaint wysyła POST na Twój adres, gdy tylko coś się wydarzy. Konfiguracja w Ustawienia firmy > Webhooki (/company-settings/webhooks). Dostępne od pakietu Starter (100 dostarczeń dziennie; od Business bez limitu).

Dostępne zdarzenia

• work_order.created — utworzono zlecenie pracy
• work_order.completed — zlecenie pracy przeszło w stan Zakończone
• work_order.status_changed — zlecenie pracy zmieniło status na dowolny; ładunek zawiera new_status. Uruchamia się obok work_order.completed, które pozostaje bez zmian
• request.created — złożono zgłoszenie serwisowe
• request.status_changed — zgłoszenie zatwierdzono, odrzucono lub anulowano
• part.low_stock — część spadła do punktu zamówienia lub poniżej
• part.out_of_stock — część spadła do zera
• part.low_stock_summary — jedno dzienne zestawienie na firmę z częściami w punkcie zamówienia lub poniżej, łącznie z tymi, które nigdy się nie poruszyły
• part.out_of_stock_summary — to samo dzienne zestawienie, dla części na zerze
• part.consumed — część zużyto na zleceniu pracy albo zwrócono
• compliance.chain_divergence — łańcuch skrótów audytu został przerwany (Enterprise)
• asset.downtime_started — otwarto postój maszyny
• asset.downtime_ended — zamknięto postój maszyny; czas trwania można już zaksięgować
• report.daily_summary — zakończone prace z danego dnia, raz dziennie o wybranej przez Ciebie godzinie
• purchase_order.created — utworzono zamówienie zakupu; ładunek zawiera zamówienie (reference, status, total_cost, currency, expected_date, erp_reference) i jego dostawcę
• purchase_order.status_changed — zamówienie zakupu zmieniło status (zatwierdzone, zamówione, anulowane…); ładunek zawiera previous_status i new_status
• purchase_order.received — przyjęto dostawę do zamówienia zakupu (wysyłane przy każdej dostawie, także częściowej); ładunek wymienia każdą pozycję z quantity_ordered, quantity_received (ta dostawa), quantity_received_total i quantity_remaining oraz receipt_id, fully_received i closed_short; new_status to PARTIALLY_RECEIVED, dopóki oczekiwany jest towar, i RECEIVED, gdy zamówienie jest kompletne lub zamknięte

part.consumed — odwzorowanie magazynu w ERP

To zdarzenie, które subskrybujesz, gdy inny system (ERP, fakturowanie, magazyn, księgowość) ma odzwierciedlać to, co utrzymanie ruchu faktycznie zużyło. Pole quantity ma znak: ujemne przy wydaniu części na zlecenie, dodatnie przy zwrocie poprzez usunięcie jej ze zlecenia — dzięki temu storno w FreeMaint tworzy odpowiadający dokument zwrotu po drugiej stronie. Pole stock_movement_id jest stałe między ponowieniami i powtórnymi wysyłkami: użyj go jako klucza idempotencji, a nigdy nie zaksięgujesz tego samego wydania dwa razy. Rzecz warta wiedzy, gdy ruch biegnie w obie strony: mutacja GraphQL adjustStock NIE wyzwala tego zdarzenia. To celowe — korekta stanu, którą Twój własny system zapisuje w FreeMaint, nigdy nie powinna wrócić do Ciebie echem i zostać zaksięgowana dwa razy. part.consumed powstaje wyłącznie ze zużycia zapisanego na zleceniu pracy wewnątrz FreeMaint. Część zawiera też custom_reference: Twój własny kod części, czyli customReference ustawione przez createPart lub updatePart, dzięki czemu system zarządzający katalogiem dopasuje każdą pozycję bez tabeli identyfikatorów FreeMaint.

{ "event": "part.consumed", "timestamp": "2026-08-19T21:04:11.000Z", "data": { "part": { "id": 812, "name": "Łożysko 6204", "part_number": "RLM-204", "reference": "PART-812", "custom_reference": "BC-10045", "unit_cost": 12.5, "unit_of_measure": "szt" }, "quantity": -2, "previous_quantity": 48, "new_quantity": 46, "work_order": { "id": 5521, "reference": "WO-2026-0412", "title": "Wymiana łożyska" }, "asset": { "id": 91, "name": "Wirówka 2" }, "location": { "id": 7, "name": "Magazyn zakładu" }, "user": { "id": 5627, "name": "A. Technik" }, "stock_movement_id": 88213, "occurred_at": "2026-08-19T21:04:11.000Z" } }

Dostarczanie i podpis

Każde dostarczenie to POST z ciałem JSON i nagłówkiem X-FreeMaint-Signature w postaci t=<sekundy unix>,v1=<hex>, gdzie v1 to HMAC-SHA256 ciągu «<t>.<surowe ciało>» z kluczem równym sekretowi Twojego webhooka. Weryfikuj na SUROWYM ciele, przed jakimkolwiek parsowaniem JSON czy ponowną serializacją. Wysyłamy też X-FreeMaint-Event i X-FreeMaint-Delivery-Id. Odpowiedź 2xx oznacza dostarczenie; błędy sieci i 5xx są ponawiane do 3 razy z wykładniczym opóźnieniem (około 2 s, 4 s, 8 s); 4xx traktujemy jako trwałą odmowę i NIE ponawiamy.

Ponowne wysłanie dostarczenia

Każda próba zostaje w historii dostarczeń webhooka, ze statusem i kodem odpowiedzi. Każde zakończone dostarczenie można stamtąd wysłać ponownie: zapisany ładunek idzie bez zmian, więc zawarte w nim klucze biznesowe (w tym stock_movement_id) pozostają te same, a poprawnie deduplikujący odbiorca nie zaksięguje operacji dwa razy. Tak nadrabia się to, co przepadło, gdy Twój endpoint był niedostępny albo omyłkowo odrzucił żądanie.

Zdjęcia (opcjonalnie)

Gdy dla webhooka włączono „Dołącz zdjęcia” (domyślnie wyłączone), obiekty "work_order" i "request" zawierają tablicę "photos": do 4 linków HTTPS do obrazów JPG, PNG, GIF lub WebP, najnowsze najpierw. Każdy link otwiera obraz bez logowania przez 7 dni, więc zapisz plik u siebie, jeśli potrzebujesz go dłużej. Ponowne wysłanie przekazuje te same linki. Pozostałe zdarzenia i webhooki się nie zmieniają. Dla "work_order.created" i "request.created" webhook z włączonym „Dołącz zdjęcia” jest wysyłany 90 sekund po zdarzeniu (pole "timestamp" zachowuje czas zdarzenia), aby zawierał zdjęcia przesłane tuż po rekordzie.

Wymagania wobec adresu URL

• Tylko https:// — zwykły http jest odrzucany
• Tylko port 443 lub 8443
• Host musi być publicznie osiągalny — zakresy loopback, prywatne i CGNAT są odrzucane
• Bez danych logowania w adresie (https://user:pass@host jest odrzucany)
• System istniejący wyłącznie w Twojej sieci wymaga publicznego endpointu lub przekaźnika (n8n, Make, Zapier) przed nim

Limity

• Starter — 100 dostarczeń dziennie na firmę
• Business — bez limitu
• Enterprise — bez limitu
• Licznik zlicza próby dostarczenia: trzy webhooki na to samo zdarzenie zużywają trzy jednostki
• Licznik dobowy zeruje się o 00:00 UTC