Webhooki

Webhooki

Webhooki pozwalają Twojemu Board wysyłać żądania HTTP do zewnętrznych usług za każdym razem, gdy podczas produkcji wystąpią określone zdarzenia — zarejestrowano ilość, rozpoczęto zadanie, zablokowano zadanie, ukończono zlecenie i nie tylko. Tak łączysz swój Board ze Slackiem, Microsoft Teams, ERP, platformą powiadomień, niestandardowym skryptem lub czymkolwiek innym, co potrafi odebrać żądanie HTTP.

Webhooki znajdują się w Ustawienia Aplikacji → Webhooki.

Uwaga: Webhooki muszą być włączone dla Twojego konta. Jeśli strona pokazuje informację, że webhooki są wyłączone, skontaktuj się ze wsparciem, aby je włączyć.

---

Spis treści

1. Czym jest webhook?
2. Kiedy używać webhooków
3. Tworzenie webhooka
4. Opis pól
5. Zdarzenia, które możesz zasubskrybować
6. Opis ładunku
7. Uwierzytelnianie (klucz API)
8. Ograniczanie do stanowisk
9. Testowanie webhooka
10. Praktyczne przykłady
11. Logi i rozwiązywanie problemów
12. Uwagi dotyczące bezpieczeństwa

---

Czym jest webhook?

Webhook to adres URL, który podajesz swojemu Board. Za każdym razem, gdy wystąpi zdarzenie, które zasubskrybowałeś, Board wysyła żądanie HTTP POST na ten URL z małym ładunkiem JSON opisującym, co się stało.

Druga strona to Twój wybór — adres URL przychodzącego webhooka Slacka, wyzwalacz „Catch Hook” w Zapier, endpoint na Twoim własnym serwerze, platforma automatyzacji, cokolwiek, co potrafi odebrać HTTP i sparsować JSON.

Webhooki są jednokierunkowe i działają na zasadzie „wyślij i zapomnij” — Board nie czeka na znaczącą odpowiedź, jedynie rejestruje kod statusu dla celów diagnostycznych. Jeśli Twój endpoint jest wolny lub tymczasowo niedostępny, Board nie ponawia automatycznie.

---

Kiedy używać webhooków

Kilka rzeczywistych przypadków użycia:

• Powiadomienia — opublikuj wiadomość w Slacku/Teams, gdy zadanie zostanie zablokowane, zlecenie ukończone lub zadanie wysokiego priorytetu rozpocznie się na konkretnym stanowisku.
• Synchronizacja ERP / księgowości — daj znać systemowi back-office, że wyprodukowano ilości, aby magazyn i fakturowanie mogły się zaktualizować.
• Niestandardowe dashboardy — zasilaj zewnętrzną Grafanę, Looker lub własny dashboard danymi produkcyjnymi w czasie rzeczywistym.
• Wyzwalanie innych automatyzacji — uruchom drukowanie etykiet wysyłkowych, instrukcji pakowania lub przepływy kontroli jakości, gdy zlecenie osiągnie status ukończonego.
• Logowanie audytowe / zgodności — strumieniuj każdą zmianę ilości lub wpis czasu do zewnętrznego archiwum.

---

Tworzenie webhooka

1. Przejdź do Ustawienia Aplikacji → Webhooki.
2. Wypełnij formularz na górze strony:
   • Źródło — które źródło zamówienia powinno wyzwolić ten webhook (lub Wszystkie źródła).
   • URL webhooka — adres URL, który wystawia Twoja zewnętrzna usługa.
   • Klucz API (opcjonalny) — token uwierzytelniający (zobacz Uwierzytelnianie).
   • Zdarzenia — zaznacz jedno lub więcej zdarzeń, które chcesz odbierać.
   • Stanowiska (opcjonalne) — wybierz konkretne stanowiska do ograniczenia lub pozostaw puste, aby wyzwalać dla wszystkich stanowisk.
3. Kliknij Dodaj (lub Aktualizuj przy edycji istniejącego webhooka).

Nowy webhook pojawi się w tabeli poniżej. Możesz go w każdej chwili edytować, usunąć lub wysłać ręczne żądanie testowe.

---

Opis pól

Pole	Opis
Źródło	Źródło zamówienia, do którego stosuje się webhook. Wybierz Wszystkie źródła, aby odbierać zdarzenia dla zamówień z dowolnego źródła, lub wybierz konkretny klucz źródła (manual, shopify itd.), aby wyzwalać tylko wtedy, gdy zamówienie zlecenia pochodzi z tego źródła.
URL webhooka	Pełny adres URL HTTPS, na który Board powinien wysłać POST. Maksymalnie 2000 znaków.
Klucz API (opcjonalny)	Jeśli ustawiony, Board wysyła go przy każdym żądaniu w dwóch nagłówkach — Authorization: Bearer <key> i X-API-Key: <key>. Użyj tego, jeśli Twój endpoint wymaga uwierzytelnienia. Pozostaw puste dla publicznych endpointów (np. przychodzących webhooków Slacka).
Zdarzenia	Jedno lub więcej zdarzeń wyzwalających ten webhook. Zobacz Zdarzenia.
Stanowiska (opcjonalne)	Lista stanowisk, do których ten webhook jest ograniczony. Puste = wyzwalaj dla wszystkich stanowisk. Zobacz Ograniczanie do stanowisk.

---

Zdarzenia, które możesz zasubskrybować

Każdy webhook wyzwala się tylko dla zaznaczonych przez Ciebie zdarzeń. Możesz zaznaczyć dowolną ich liczbę.

qty_changed — Zmiana ilości

Wyzwala się za każdym razem, gdy zarejestrowana zostanie ilość na stanowisku w dowolnym zleceniu — przez dashboard, Kiosk, aplikację mobilną lub API. Ładunek zawiera stanowisko, całkowitą wytworzoną dotąd ilość dla zlecenia oraz pola identyfikujące zlecenie i zamówienie.

Przykładowe zastosowanie: zasilanie systemu ERP w czasie rzeczywistym postępem produkcji.

time_log_saved — Zapisano wpis czasu

Wyzwala się, gdy zostanie utworzony wpis ewidencji czasu — albo ręcznie przez przycisk „Wyślij” na Kiosku, albo gdy zatrzymany zostanie licznik. Ładunek zawiera czas trwania w minutach, pracownika, stanowisko, dowolną notatkę oraz ilość (jeśli była), która została zapisana w tym samym czasie.

Przykładowe zastosowanie: logowanie produktywności do systemu fakturowania/płacowego.

job_blocked — Zadanie zablokowane

Wyzwala się, gdy pracownik oznaczy zadanie jako zablokowane (na przykład „brak materiału”, „awaria maszyny”). Ładunek zawiera notatkę blokady wyjaśniającą przyczynę.

Przykładowe zastosowanie: opublikowanie natychmiastowego alertu w Slacku, aby brygadzista mógł zbadać sprawę.

job_completed — Zadanie ukończone (całe zlecenie)

Wyzwala się, gdy całe zlecenie zostanie ukończone — tj. gdy status zlecenia przechodzi do skonfigurowanego statusu ukończenia (albo zmienionego ręcznie, albo automatycznie, gdy każde stanowisko osiągnie swoją planowaną ilość). Ładunek zawiera całkowity czas trwania w minutach po wszystkich wpisach ewidencji czasu na zleceniu.

Przykładowe zastosowanie: wyzwolenie przepływu etykiety wysyłkowej lub fakturowania, gdy zlecenie jest w pełni gotowe.

task_started — Zadanie rozpoczęte na stanowisku

Wyzwala się raz na stanowisko na zlecenie, przy pierwszym zarejestrowaniu aktywności. Aktywność oznacza zarejestrowanie pierwszej ilości > 0 lub pierwsze uruchomienie licznika ewidencji czasu na tym stanowisku — to, co nastąpi pierwsze. Ładunek zawiera znacznik czasu ISO started_at.

Przykładowe zastosowanie: powiadom brygadzistę, że rozpoczęła się praca nad krytycznym krokiem, aby wiedział, że produkcja faktycznie ruszyła.

task_completed — Zadanie ukończone na stanowisku

Wyzwala się raz na stanowisko na zlecenie, gdy stanowisko po raz pierwszy osiągnie swoją planowaną ilość (lub dla działów ze współdzieloną ilością, w momencie gdy zsumowana ilość działu osiągnie sumę zlecenia). Ładunek zawiera znacznik czasu ISO completed_at.

Przykładowe zastosowanie: wyzwol następny system downstream (pakowanie, QA, wysyłka) w chwili, gdy konkretny etap produkcji się kończy.

Idempotencja dla task_started / task_completed: każde z nich jest zapisywane trwale na wierszu stanowiska, więc wyzwala się tylko przy pierwszym spełnieniu warunku. Zarejestrowanie większej ilości lub ponowne uruchomienie licznika po pierwszym trafieniu nie spowoduje ponownego wyzwolenia tych zdarzeń.

---

Opis ładunku

Każde zdarzenie wysyła obiekt JSON przez HTTP POST. Część pól jest wspólna dla wszystkich zdarzeń; inne są specyficzne dla typu zdarzenia. Puste pola / null są pomijane, aby ładunki były zwarte.

Pola podstawowe (obecne dla wszystkich zdarzeń)

{
    "event": "qty_changed",
    "job_ref": "PB-0042",
    "order_ref": "PO-2025-001",
    "order_external_id": "EXT-12345",
    "manufactured_qty": 7,
    "sku": "TABLE-OAK-90",
    "name": "Oak Coffee Table",
    "external_id": "ORD-7890",
    "department": "Assembly",
    "workstation": "Station A",
    "workstation_id": 12
}

Pole	Znaczenie
event	Klucz zdarzenia — jedno z sześciu wymienionych powyżej.
job_ref	Numer referencyjny zlecenia na Twoim Board.
order_ref	Referencja nadrzędnego zamówienia, jeśli istnieje.
order_external_id	Zewnętrzne ID zamówienia (np. ID zamówienia Shopify).
manufactured_qty	Całkowita ilość wytworzona dla tego zlecenia na wszystkich stanowiskach. (Dla time_log_saved to suma stanowiska, nie zlecenia.)
sku	SKU zlecenia.
name	Nazwa zlecenia.
external_id	Zewnętrzne ID zlecenia (np. identyfikator systemu upstream).
department	Dział stanowiska, którego dotyczy zdarzenie, jeśli stanowisko jest w kontekście.
workstation	Nazwa stanowiska, którego dotyczy.
workstation_id	Numeryczne ID stanowiska, którego dotyczy.

Pola department, workstation i workstation_id są obecne za każdym razem, gdy zdarzenie odnosi się do konkretnego stanowiska (czyli wszystkie zdarzenia z wyjątkiem job_completed, które dotyczy całego zlecenia).

Dodatkowe pola per zdarzenie

Zdarzenie	Dodatkowe pola
qty_changed	—
time_log_saved	mode ("manual" lub "work_stopped"), log_qty, log_note, duration_minutes, employee (obiekt z id, name, surname)
job_blocked	block_note
job_completed	status (nazwa statusu ukończenia), total_duration_minutes
task_started	started_at (znacznik czasu ISO 8601)
task_completed	completed_at (znacznik czasu ISO 8601)

Przykład: ładunek task_started

{
    "event": "task_started",
    "job_ref": "PB-0042",
    "order_ref": "PO-2025-001",
    "manufactured_qty": 0,
    "sku": "TABLE-OAK-90",
    "name": "Oak Coffee Table",
    "department": "Assembly",
    "workstation": "Station A",
    "workstation_id": 12,
    "started_at": "2026-05-27T08:14:32+00:00"
}

Przykład: ładunek time_log_saved

{
    "event": "time_log_saved",
    "job_ref": "PB-0042",
    "manufactured_qty": 5,
    "sku": "TABLE-OAK-90",
    "name": "Oak Coffee Table",
    "department": "Assembly",
    "workstation": "Station A",
    "workstation_id": 12,
    "mode": "work_stopped",
    "log_qty": 2,
    "log_note": "Two units finished, third in progress",
    "duration_minutes": 47,
    "employee": { "id": 8, "name": "Jan", "surname": "Kowalski" }
}

---

Uwierzytelnianie (klucz API)

Jeśli Twój endpoint wymaga uwierzytelnienia, wypełnij pole Klucz API. Board wysyła go przy każdym żądaniu w dwóch nagłówkach:

Authorization: Bearer <your-api-key>
X-API-Key: <your-api-key>

Większość endpointów akceptuje którąkolwiek formę, więc nie ma znaczenia, którą sprawdzisz po stronie odbiorczej.

Pozostaw Klucz API pusty dla publicznych endpointów, takich jak przychodzące webhooki Slacka — nie oczekują żadnego nagłówka uwierzytelniania.

---

Ograniczanie do stanowisk

Domyślnie webhook wyzwala się dla każdego stanowiska. Opcjonalne pole Stanowiska pozwala go ograniczyć.

Pusta lista (domyślnie)

Webhook wyzwala się dla wszystkich stanowisk. To pierwotne zachowanie — istniejące webhooki utworzone przed tą funkcją pozostają nienaruszone.

Konkretne stanowiska

Webhook wyzwala się tylko, gdy stanowisko zdarzenia znajduje się na liście. Przydatne, gdy:

• Chcesz, aby kanał Slack otrzymywał alerty tylko dla stanowisk zespołu lakierni.
• Chcesz integracji ERP, której interesują tylko stanowiska montażu końcowego.
• Różne zespoły powinny otrzymywać różne powiadomienia.

Zachowanie ze zdarzeniami niezwiązanymi ze stanowiskiem

Zdarzenie job_completed jest wyzwalane na poziomie całego zlecenia (bez konkretnego stanowiska). Webhook z wybranym jednym lub większą liczbą stanowisk nie wyzwoli się dla job_completed — z założenia. Jeśli chcesz, aby webhook odbierał job_completed, pozostaw listę stanowisk pustą (lub utwórz drugi webhook tylko dla tego zdarzenia).

W połączeniu ze Źródłem

Filtr stanowisk jest stosowany na wierzchu filtra źródła. Webhook z source=shopify i stanowiskami [A, B] wyzwala się tylko, gdy zdarzenie pasuje do obu — zdarzenie zlecenia ze źródła Shopify dziejące się na stanowisku A lub B.

---

Testowanie webhooka

Tabela webhooków ma ikonę papierowego samolotu (✈) obok każdego wiersza — kliknij ją, aby otworzyć dialog testowy.

1. Wybierz zdarzenie z zasubskrybowanych zdarzeń Twojego webhooka.
2. Przykładowy ładunek jest renderowany jako JSON. Edytuj go swobodnie — zmień dowolne pole, aby zasymulować rzeczywisty scenariusz.
3. Kliknij Wyślij test. Dialog przełącza się na panel wyniku pokazujący:
   • Kod statusu HTTP zwrócony przez Twój endpoint
   • Czas zajęty (w milisekundach)
   • Treść odpowiedzi (skrócona do 2 KB)
   • Dowolny błąd połączenia
4. Kliknij Powrót do edycji, aby poprawić ładunek i spróbować ponownie.

To najszybszy sposób, aby zweryfikować, że Twój endpoint jest osiągalny, poprawnie parsuje ładunek i odpowiada statusem 2xx.

---

Praktyczne przykłady

1. Alert Slack przy zablokowaniu dowolnego zadania

• Źródło: Wszystkie źródła
• URL: adres URL przychodzącego webhooka Slacka
• Klucz API: pusty
• Zdarzenia: tylko job_blocked
• Stanowiska: puste

W Slacku ładunek przychodzi jako JSON; możesz go ładnie sformatować przekaźnikiem (np. Cloudflare Worker zamieniający block_note + workstation w wiadomość Slacka). Albo użyj usługi takiej jak Zapier pomiędzy, aby zrobiła formatowanie.

2. Wyślij e-mail do brygadzisty, gdy lakiernia ukończy zlecenie

• Źródło: Wszystkie źródła
• URL: URL „Catch Hook” Zapier połączony z krokiem Gmail „Wyślij e-mail”
• Zdarzenia: task_completed
• Stanowiska: zaznacz wszystkie stanowiska lakierni

Webhook wyzwala się w chwili, gdy część lakiernicza dowolnego zlecenia jest gotowa. Zapier formatuje e-mail z pól ładunku.

3. Przekaż wytworzone ilości do ERP

• Źródło: konkretne zewnętrzne źródło (np. shopify)
• URL: endpoint przychodzący Twojego ERP
• Klucz API: token API Twojego ERP
• Zdarzenia: qty_changed, job_completed
• Stanowiska: puste (chcesz wszystkich)

ERP otrzymuje ładunek po każdej zmianie ilości plus końcowe powiadomienie o całym zleceniu, gdy jest w pełni ukończone.

4. Różne powiadomienia per dział

Utwórz trzy oddzielne webhooki, każdy ograniczony do stanowisk swojego działu:

• „Slack Montaż” → task_started, task_completed, job_blocked, stanowiska = tylko stanowiska montażu
• „Slack Lakiernia” → te same zdarzenia, stanowiska = tylko stanowiska lakierni
• „Slack Pakowanie” → te same zdarzenia, stanowiska = tylko stanowiska pakowania

Każdy zespół widzi tylko alerty, które są dla niego istotne.

---

Logi i rozwiązywanie problemów

Każde żądanie webhooka — zarówno rzeczywiste zdarzenia, jak i ręczne testy — jest dopisywane do logu per najemca na serwerze pod:

storage/logs/webhooks/webhook_tennent_id_<tenant_id>.log

Każda linia to obiekt JSON ze znacznikiem czasu, zdarzeniem, URL, statusem HTTP, czasem trwania, ładunkiem, treścią odpowiedzi i dowolnym błędem. To pierwsze miejsce, w które warto zajrzeć, gdy webhook wydaje się nie dostarczać.

Typowe problemy

• Endpoint zwraca 4xx / 5xx — sprawdź treść odpowiedzi w logu. Board przestaje wysyłać przy następnym zdarzeniu tylko, jeśli URL zostanie usunięty; nie ponawia bieżącego zdarzenia automatycznie.
• Brak linii logu w ogóle dla zdarzenia — Twój webhook nie pasuje. Zweryfikuj filtry źródło, zdarzenia i stanowiska. Dialog Test omija te filtry i jest najszybszym sposobem potwierdzenia, że URL działa.
• Wolny endpoint — timeout żądania Board to 10 sekund. Jeśli Twój endpoint trwa dłużej, połączenie zostaje przerwane, a błąd zalogowany.
• Błędy HTTPS — upewnij się, że Twój endpoint ma prawidłowy certyfikat. Board nie pozwala na certyfikaty samopodpisane.
• Wyłączona flaga najemcy — strona pokazuje informację o wyłączeniu, jeśli webhooki są wyłączone dla Twojego konta. Skontaktuj się ze wsparciem.

---

Uwagi dotyczące bezpieczeństwa

• Sam URL jest poświadczeniem, gdy nie ustawiono klucza API. Każdy, kto zna URL nieuwierzytelnionego webhooka (np. przychodzącego webhooka Slacka), może na niego wysyłać. Traktuj URL-e nieuwierzytelnione jako sekrety i nie udostępniaj ich publicznie.
• Używaj pola Klucz API, ilekroć Twój endpoint wspiera uwierzytelnianie. To darmowe podniesienie bezpieczeństwa — Board wysyła go przy każdym żądaniu.
• HTTPS jest wymagany dla każdego endpointu obsługującego rzeczywiste dane produkcyjne. Pole URL webhooka akceptuje też http://, ale używaj go tylko do lokalnego developmentu.
• Ładunki zawierają identyfikowalne informacje o zamówieniu/kliencie. Upewnij się, że odbierająca usługa jest zatwierdzona do obsługi tych danych — zwłaszcza dla źródeł zewnętrznych, platform automatyzacji firm trzecich i każdej usługi, która przechowuje lub loguje ładunki.
• Webhooki są per najemca. Zdarzenia z danych jednego najemcy nigdy nie mogą trafić do webhooków innego najemcy.