Webhooki
Webhook pozwala FlexiProject powiadomić zewnętrzny system w chwili, gdy w organizacji coś się wydarzy. Zamiast wielokrotnie odpytywać API, czy coś się zmieniło, system odbierający dostaje żądanie HTTP z danymi zdarzenia od razu po jego wystąpieniu.
Jeden webhook łączy jedno zdarzenie z jednym adresem odbiorcy. Aby wysyłać dwa różne zdarzenia pod ten sam adres albo to samo zdarzenie do dwóch systemów, tworzy się po dwa webhooki.
Webhooki konfiguruje się w Ustawieniach systemowych > Webhooki. Sekcja jest dostępna dla administratora systemu (zobacz Użytkownicy i uprawnienia). Do odczytu danych innym kanałem służy API.
Zdarzenia
FlexiProject raportuje cztery zdarzenia. Każdy webhook nasłuchuje dokładnie jednego z nich, wybranego z listy Zdarzenie.
| Zdarzenie | Kiedy FlexiProject wysyła żądanie | Dane właściwe dla zdarzenia |
|---|---|---|
| Projekt utworzony | Powstał nowy projekt, w dowolny sposób: od zera, z szablonu, przez sklonowanie, przez import pliku MS Project lub Excel albo z pomocą AI. | projectId, projectName, createdAt |
| Projekt usunięty | Projekt został usunięty. | projectId, projectName |
| Akceptacja rozpoczęta | Wniosek o zmianę został przekazany do akceptacji i ruszyła jego ścieżka akceptacji. | changeRequestId, changeRequestName, projectId, projectName, date |
| Akceptacja zakończona | Ścieżka akceptacji zakończyła się decyzją: zatwierdzeniem, odrzuceniem albo anulowaniem. | changeRequestId, changeRequestName, projectId, projectName, decisionDate, status |
Każde żądanie niesie dodatkowo nazwę zdarzenia (event), moment jego wygenerowania (timestamp) oraz identyfikator (userId) i adres e-mail (userEmail) użytkownika, którego działanie je wywołało. Format całego żądania opisuje Format żądania HTTP. Akceptacje opisuje dział Akceptacje.
Konfiguracja webhooka
Lista webhooków
Strona Webhooki pokazuje wszystkie webhooki organizacji w trzech kolumnach: Zdarzenie, URL odbiorcy i Opis. Gdy nic nie zdefiniowano, widać komunikat Brak webhooków.
Dodawanie webhooka
- Po kliknięciu przycisku dodawania nad listą otworzy się okno Dodaj webhook.
- Należy wybrać Zdarzenie. Domyślnie jest ustawione Projekt utworzony.
- Następnie należy wpisać URL odbiorcy — adres, pod który FlexiProject wyśle żądanie. Pole jest obowiązkowe i wymaga pełnego adresu razem z protokołem, na przykład
https://example.com/hooks/flexiproject. Niepełny adres zostaje odrzucony komunikatem o błędzie przetwarzania danych. - Opcjonalnie można wpisać Opis — notatkę dla zespołu, widoczną tylko na liście.
- Po kliknięciu przycisku Zapisz webhook pojawi się na liście, a zaraz potem wyświetli się okno Sekret.
Sekret
Okno Sekret zawiera komunikat: Webhook został utworzony. Poniżej znajduje się sekret, który zostanie wyświetlony tylko raz. Skopiuj go i przechowaj w bezpiecznym miejscu. Po kliknięciu przycisku Kopiuj wartość trafi do schowka (komunikat Skopiowano do schowka), a stamtąd należy ją zapisać w systemie odbierającym. Sekret służy do podpisywania każdego żądania, dzięki czemu odbiorca może potwierdzić, że żądanie pochodzi z FlexiProject (zobacz Format żądania HTTP).
Po zamknięciu okna pełna wartość nie jest już dostępna nigdzie w aplikacji. W otwartym później webhooku pole Sekret pokazuje tylko pierwsze i ostatnie cztery znaki, a środek zastępują gwiazdki; pola nie można edytować.
Edycja webhooka
Po kliknięciu nazwy zdarzenia na liście otworzy się okno Edytuj webhook. Można w nim zmienić zdarzenie, adres odbiorcy i opis, a następnie kliknąć Zapisz. Sekret pozostaje bez zmian — edycja nigdy nie wystawia nowego. Zamknięcie okna z niezapisanymi zmianami wywołuje pytanie Czy chcesz przejść dalej i porzucić zmiany?.
Testowanie webhooka
Po kliknięciu przycisku Testuj w oknie edycji zapisanego webhooka zostanie wysłane pod skonfigurowany adres żądanie w formacie wybranego zdarzenia, wypełnione przykładowymi danymi (na przykład projektem Test Project), a aplikacja potwierdzi to komunikatem Pomyślnie wysłano żądanie testowe. Komunikat potwierdza wysłanie, nie przyjęcie przez odbiorcę — wynik trzeba sprawdzić po stronie odbierającej.
Usuwanie webhooka
Po kliknięciu przycisku Usuń w oknie webhooka należy potwierdzić pytanie Czy na pewno chcesz usunąć webhook?. Webhook zostanie usunięty i od tej chwili zdarzenie nie będzie wysyłane pod ten adres. Usunięcia nie można cofnąć; wznowienie wysyłki to nowy webhook, a więc i nowy sekret.
Format żądania HTTP
FlexiProject wysyła pod skonfigurowany adres żądanie POST z treścią w formacie JSON.
Nagłówki
| Nagłówek | Zawartość |
|---|---|
X-FlexiProject-Event |
Nazwa zdarzenia: ProjectCreated, ProjectDeleted, AcceptanceStarted albo AcceptanceCompleted. |
X-FlexiProject-Delivery |
Identyfikator doręczenia. Jest taki sam we wszystkich ponowieniach tego samego zdarzenia, więc po nim rozpoznaje się duplikaty. |
X-FlexiProject-Timestamp |
Moment wysłania żądania. |
X-FlexiProject-Signature |
Podpis treści żądania w postaci sha256=<wartość>. |
Weryfikacja podpisu
Podpis to HMAC-SHA256 z surowej treści żądania, policzony z sekretem webhooka jako kluczem i zapisany szesnastkowo małymi literami. Odbiorca liczy tę samą wartość z otrzymanej treści i porównuje ją z częścią nagłówka X-FlexiProject-Signature po sha256=. Jeśli wartości się różnią, żądanie trzeba odrzucić — nie pochodzi z tej organizacji w FlexiProject.
Przykładowa treść
{
"projectId": "6712f0a1c3d4e5f601234567",
"projectName": "Modernizacja magazynu",
"createdAt": "2026-09-21T08:14:02Z",
"userId": "a3f1c7de-1b20-4f9e-9a55-0c2d8e7b41aa",
"userEmail": "anna.kowalska@example.com",
"event": "ProjectCreated",
"timestamp": "2026-09-21T08:14:02Z"
}Odpowiedź i ponowienia
Odbiorca odpowiada statusem powodzenia (2xx), gdy tylko przyjmie żądanie. Każda inna odpowiedź albo jej brak liczy się jako nieudane doręczenie.
Nieudane doręczenie jest ponawiane automatycznie z rosnącym odstępem: po 1, 2, 4, 8, 16, 32, 64, 128, 256 i 512 minutach. Próby rozkładają się na mniej więcej siedemnaście godzin, więc odbiorca niedostępny przez pewien czas nie traci zdarzenia. Każda próba powtarza tę samą wartość X-FlexiProject-Delivery, dlatego obsługa po stronie odbiorcy musi znosić otrzymanie tego samego zdarzenia więcej niż raz.
