Webhooki — powiadomienia o zdarzeniach w restauracji

Webhook to sposób, żeby Twój system dowiedział się o zdarzeniu w restauracji od razu, bez dopytywania. Gdy wydarzy się coś, co wybierzesz — na przykład zamknięcie rachunku — Fodimi wysyła zapytanie POST na wskazany adres.

Dzięki temu nie musisz co minutę odpytywać API „czy coś się zmieniło". Webhooki najczęściej podłącza się do CRM-a, Make.com albo Zapiera.

Znajdziesz je w Integracje → Webhooki.

Jak dodać webhook

Wypełniasz dwa pola:

• Nazwa — ułatwia rozpoznanie webhooka w logach
• Adres URL — musi być publiczny i zaczynać się od https://. Przekierowania nie są obsługiwane, więc podaj adres docelowy

Przełącznik Webhook aktywny pozwala tymczasowo wstrzymać wysyłkę bez usuwania konfiguracji.

Jakie zdarzenia możesz wybrać

Rachunki i zamówienia:

• Zamknięcie rachunku (order.closed) — rachunek zakończony, z paragonem fiskalnym lub bez. Ponowne zamknięcie wysyła zdarzenie jeszcze raz
• Anulowanie zamówienia (order.canceled) — wraz z powodem
• Zmiana statusu zamówienia (order.status_changed) — zawiera poprzedni i nowy status

Klienci i lojalność:

• Nowy klient (client.created) — rejestracja konta, dodanie klienta w POS, panelu albo przez API
• Zmiana danych klienta (client.updated) — imię, telefon, e-mail, adres lub zgody marketingowe
• Zmiana punktów klienta (client.points_changed) — z różnicą, saldem i powodem zmiany

Dostawy:

• Zmiana statusu dostawy (delivery.status_changed) — kurier przypisany, odebrał zamówienie, w drodze, dostarczone. Działa dla własnych kierowców i firm kurierskich

Zawężanie wysyłki

Sekcja W jakich sytuacjach jest opcjonalna — puste pole oznacza „wszystkie". Możesz ograniczyć wysyłkę do wybranych lokali, źródeł zamówienia, sposobów realizacji albo rachunków powyżej określonej kwoty.

Dwa warunki warto znać bliżej:

• Tylko zamówienia z przypisanym klientem — przydatne dla CRM-a, bo pomija rachunki bez konta klienta
• Paragon fiskalny — uwaga: paragon bywa zapisywany chwilę po zamknięciu rachunku, więc przy ustawieniu „tylko fiskalne" rachunki fiskalizowane później mogą zostać pominięte

Sekret podpisu

Sekret powstaje automatycznie po zapisaniu webhooka i służy do weryfikacji, że wiadomość naprawdę pochodzi z Fodimi. Nie udostępniaj go publicznie. W razie potrzeby możesz wygenerować nowy przyciskiem Nowy sekret.

Do każdej wiadomości dołączamy trzy nagłówki:

• X-Fodimi-Event — nazwa zdarzenia
• X-Fodimi-Delivery — identyfikator wysyłki, stały przy ponowieniach, więc pozwala pominąć duplikaty
• X-Fodimi-Signature — podpis w postaci t=…,v1=…

Podpis liczysz tak:

v1 = HMAC_SHA256(secret, t + "." + body)

Odrzucaj wiadomości ze znacznikiem czasu t starszym niż 5 minut — to chroni przed ponownym wysłaniem przechwyconej wiadomości.

Sprawdź, czy działa

Przyciskiem Wyślij test sprawdzisz, czy Twój serwer odbiera wiadomości. Wybierasz zdarzenie, a my wysyłamy przykładowe dane na zapisany adres. Wysyłka testowa jest oznaczona w logach etykietą Test, więc od razu odróżnisz ją od prawdziwych zdarzeń.

Co widać na liście

Przy każdym webhooku widzisz wybrane zdarzenia, status oraz liczbę udanych wysyłek i błędów z ostatnich 7 dni. Jeśli w kolumnie błędów rośnie liczba, zajrzyj do logów.

Logi wysyłek

Zakładka Logi wysyłek pokazuje historię z ostatnich 30 dni — datę, webhook, zdarzenie, status, kod HTTP i czas odpowiedzi. Wpisy da się filtrować i wyszukiwać po identyfikatorze zamówienia, klienta albo wysyłki.

Na zrzucie powyżej widać wysyłkę zakończoną kodem 405, bo adres użyty w przykładzie nie przyjmuje zapytań POST. Dokładnie tak wygląda nieudana próba — i właśnie wtedy przydaje się przycisk Ponów.

Szczegóły wysyłki

Po kliknięciu Szczegóły zobaczysz pełną treść wysłanej wiadomości oraz odpowiedź serwera. To pierwsze miejsce, do którego warto zajrzeć, gdy integracja nie działa — od razu widać, czy problem jest po naszej, czy po Twojej stronie.

Wiadomość jest krótka i zawiera identyfikatory oraz samą zmianę: uid rachunku, nazwę zdarzenia, czas i nowy status. Pełne dane pobierzesz z API po uid — dzięki temu wiadomości są szybkie i nie przenoszą niepotrzebnie dużych ładunków.

Ponawianie i automatyczne wyłączanie

Jeśli Twój serwer nie odpowie kodem z zakresu 2xx, ponawiamy wysyłkę po 10 sekundach, 1 minucie i 5 minutach. Po 20 nieudanych wysyłkach z rzędu webhook zostaje wyłączony — wtedy trzeba naprawić odbiornik i włączyć go ręcznie.

Dlatego warto, żeby Twój endpoint odpowiadał kodem 2xx od razu po przyjęciu wiadomości, a dłuższe przetwarzanie wykonywał już po odpowiedzi.