Webhooki

Webhooki w Z24 umożliwiają automatyczne przekazywanie zdarzeń (np. nowych zamówień lub zmian statusów) do zewnętrznych systemów takich jak Zapier, Make, n8n, ERP czy własne API integratora.

Webhook jest wywoływany asynchronicznie w momencie wystąpienia zdarzenia i nie blokuje pracy aplikacji Z24.

Konfiguracja webhooka

Webhooki konfigurowane są w panelu Z24:

Ustawienia → Integracje → Webhooki

Podczas tworzenia webhooka należy ustawić:

1. Nazwa

Dowolna nazwa identyfikująca webhook (np. „Zapier”, „ERP”, „System magazynowy”).

2. Adres URL webhooka

Adres endpointu HTTP, na który Z24 będzie wysyłać zdarzenia metodą POST.

Endpoint musi:

• obsługiwać HTTPS

• przyjmować dane w formacie JSON

• odpowiadać kodem HTTP 2xx w przypadku poprawnego przetworzenia zdarzenia

3. Sekret podpisu (opcjonalny, zalecany)

Sekret używany do podpisywania webhooków (HMAC SHA-256).

Pozwala odbiorcy zweryfikować, że webhook pochodzi z Z24 i że dane nie zostały zmodyfikowane.

4. Zakres zdarzeń

Webhook może reagować na wybrane zdarzenia, np.:

• Zamówienia → zmiana statusu na „Nowe”

• (w przyszłości: inne statusy, eksporty, zdarzenia logistyczne)

5. Dystrybutor (opcjonalny)

Webhook może być przypisany do konkretnego dystrybutora / oddziału.

• jeśli dystrybutor jest wybrany → webhook otrzymuje tylko zamówienia przypisane do tego dystrybutora

• jeśli dystrybutor nie jest wybrany → webhook otrzymuje wszystkie zamówienia zespołu, niezależnie od dystrybutora

To pozwala np.:

• wysyłać zamówienia do różnych systemów ERP w zależności od dystrybutora

• integrować wiele oddziałów jednego dostawcy niezależnie

Struktura webhooka (payload)

Webhook wysyłany jest metodą POST z nagłówkiem:

Content-Type: application/json

Przykładowy payload:

{
  "event": "document.submitted",
  "team_guid": "8182e432-e5da-4766-ab5d-5a6c88e40bdd",
  "order_guid": "a1b148fa-4b3e-4a8c-9427-50703d416a1f",
  "activated_at": "2026-01-28T12:10:36.529084+00:00",
  "distributor_guid": "b9f1d3e1-1d44-4c2a-9f3b-8e7c4d5a1111"
}

Znaczenie pól

activated_at oznacza moment, w którym zdarzenie zostało wywołane, a nie moment utworzenia rekordu w bazie danych.

Nagłówki HTTP wysyłane przez Z24

Każdy webhook zawiera dodatkowe nagłówki techniczne:

X-Z24-Delivery: <unikalny identyfikator wysyłki>
X-Z24-Timestamp: <czas UNIX>
X-Z24-Signature: sha256=<podpis>
X-Z24-Event: order.submitted

Opis nagłówków

Weryfikacja podpisu (zalecane)

Jeśli webhook ma ustawiony sekret podpisu, odbiorca powinien zweryfikować podpis:

1. Odczytać raw body JSON (bez modyfikacji)

2. Zbudować ciąg:

{timestamp}.{raw_body}

3. Wygenerować HMAC SHA-256 z użyciem sekretu

4. Porównać wynik z X-Z24-Signature

Webhook należy odrzucić, jeśli:

• podpis się nie zgadza

• timestamp jest zbyt stary (ochrona przed replay attack)

Odpowiedzi webhooka

Z24 interpretuje odpowiedź endpointu w następujący sposób:

Sukces

• kod HTTP 2xx

• webhook uznany za dostarczony

• brak ponownych prób

Błąd

• brak odpowiedzi

• timeout

• kod HTTP >= 400

Webhook zostanie ponowiony automatycznie zgodnie z harmonogramem retry.

Retry i niezawodność

Z24 posiada wbudowany mechanizm kolejkowania i ponownych prób.

Webhook jest ponawiany maksymalnie 7 razy z rosnącym opóźnieniem:

• 1 min

• 5 min

• 15 min

• 1 h

• 4 h

• 12 h

• 24 h

Po nieudanych próbach webhook otrzymuje status failed i nie jest już wysyłany automatycznie.

Dobre praktyki po stronie integratora

Zalecamy, aby endpoint webhooka:

• odpowiadał szybko (do kilku sekund)

• nie wykonywał długich operacji synchronicznie

• zapisywał zdarzenie lokalnie i przetwarzał je asynchronicznie

• był idempotentny (możliwe ponowne wysłanie tego samego zdarzenia)

Podsumowanie

Webhooki w Z24:

• są bezpieczne (HMAC)

• odporne na błędy (kolejka + retry)

• konfigurowalne per zespół i per dystrybutor

• przeznaczone do integracji produkcyjnych

W przypadku pytań technicznych integrator może skontaktować się z zespołem Z24 lub skorzystać z dokumentacji deweloperskiej.