Webhooki DataFirefly: kompletny przewodnik

Prezentacja

Webhooki DataFirefly łączą Twój sklep PrestaShop 8 i 9 z ponad 5000 aplikacji, w obu kierunkach. W trybie wychodzącym sklep wysyła swoje zdarzenia (zamówienia, klienci, stany magazynowe) do Zapier, Make, n8n lub dowolnego endpointu HTTP. W trybie przychodzącym te same narzędzia mogą przesyłać dane do sklepu przez zabezpieczone API.

Moduł opiera się na trzech filarach: asynchronicznej kolejce (żadne zamówienie nie jest spowalniane), automatycznych ponowieniach z wykładniczym backoffem oraz podpisie HMAC-SHA256 gwarantującym autentyczność wiadomości.

Instalacja

1. Pobierz archiwum dfwebhooks.zip ze swojego konta DataFirefly.
2. W back-office przejdź do Moduły > Menedżer modułów > Wgraj moduł i wybierz plik ZIP.
3. Kliknij Instaluj, a następnie Konfiguruj.
4. Trafiasz na główny ekran, który wyświetla adres workera cron oraz adres API przychodzącego.

1. Zaplanowanie workera cron (przepływ wychodzący)

Webhooki wychodzące nie są wysyłane natychmiast: trafiają do kolejki, a następnie są dostarczane przez worker uruchamiany cyklicznie. Skopiuj adres crona wyświetlony na ekranie konfiguracji i zaplanuj go co 1 do 5 minut.

*/2 * * * * curl -s "https://twoj-sklep.pl/index.php?fc=module&module=dfwebhooks&controller=cron&token=TWOJ_TOKEN" >/dev/null 2>&1

Przy każdym przebiegu worker przetwarza do 50 oczekujących dostarczeń, wykonuje potrzebne ponowienia i czyści stare wpisy dziennika zgodnie ze skonfigurowanym czasem retencji.

2. Tworzenie endpointu wychodzącego

Endpoint łączy zdarzenie z adresem docelowym. Na ekranie głównym kliknij Dodaj i uzupełnij:

• Nazwa: wewnętrzna etykieta (np. „Nowe zamówienie do Zapier”).
• Zdarzenie: zdarzenie wyzwalające (lista poniżej).
• Adres URL: wklej adres „Catch Hook” z Zapier lub „Custom Webhook” z Make.
• Sekret podpisu (opcjonalnie): jeśli podany, każdy payload jest podpisywany w HMAC-SHA256.

Filtry warunkowe

Webhook możesz wysyłać tylko wtedy, gdy spełnione są określone warunki. Reguły zapisuje się w formacie JSON i łączy logicznym I. Dostępne operatory: eq, neq, gt, gte, lt, lte, in, contains.

[{"field":"order.total_paid","op":"gte","value":100}]

Ten przykład wyzwala webhook tylko dla zamówień, których zapłacona kwota jest równa 100 lub wyższa.

Mapowanie pól

Domyślnie wysyłany jest pełny payload. Aby przesyłać tylko wybrane pola w konkretnym formacie, zdefiniuj mapowanie: kluczem jest nazwa wyjściowa, wartością ścieżka w payloadzie.

{"email":"customer.email","total":"order.total_paid"}

3. Dostępne zdarzenia wychodzące

• order.created: zamówienie zostało właśnie zatwierdzone.
• order.status.updated: zmienia się status zamówienia.
• order.refunded: zamówienie przechodzi w status zwrotu.
• customer.created: rejestruje się nowy klient.
• address.created: powstaje nowy adres.
• product.created: dodano produkt.
• product.updated: produkt został zmodyfikowany.
• product.stock.low: stan magazynowy spada poniżej skonfigurowanego progu.
• review.created: opinia została zatwierdzona (wymaga zgodnego modułu opinii).

4. API przychodzące (Zapier, Make, n8n do PrestaShop)

API przychodzące pozwala Twoim automatyzacjom modyfikować sklep. Jest chronione tokenem i opcjonalnie podpisem HMAC.

Tworzenie tokenu

W panelu Tokeny przychodzące nadaj etykietę, wybierz dozwolone zakresy (orders, products, customers) i, jeśli chcesz, sekret podpisu. Wygenerowany token wklejasz do swojego narzędzia.

Wysłanie żądania

Wykonaj POST na adres API przychodzącego. Token przekazuje się w nagłówku X-DF-Token (lub w parametrze ?token=). Treść to JSON z polem action i obiektem data.

POST https://twoj-sklep.pl/index.php?fc=module&module=dfwebhooks&controller=api
X-DF-Token: TWOJ_TOKEN
Content-Type: application/json

{"action":"order.status.update","data":{"id_order":42,"id_order_state":4}}

5. Dostępne akcje przychodzące

• order.status.update (zakres orders): zmienia status zamówienia. Pola: id_order, id_order_state, send_email (opcjonalnie).
• order.get (zakres orders): pobiera zamówienie. Pole: id_order.
• product.stock.update (zakres products): ustawia stan magazynowy. Pola: id_product, quantity, id_product_attribute (opcjonalnie).
• product.upsert (zakres products): tworzy lub aktualizuje produkt po jego reference.
• customer.upsert (zakres customers): tworzy lub aktualizuje klienta po jego email.
• customer.get (zakres customers): pobiera klienta po email lub id_customer.

6. Weryfikacja podpisu HMAC

Jeśli na endpoincie (wychodzącym) lub tokenie (przychodzącym) skonfigurowano sekret, wiadomość zawiera nagłówek X-DF-Signature: sha256=.... Aby go zweryfikować po stronie odbiorczej, przelicz HMAC surowej treści swoim sekretem i porównaj w czasie stałym.

$expected = "sha256=" . hash_hmac("sha256", $rawBody, $secret);
if (hash_equals($expected, $signatureHeader)) {
    // podpis prawidłowy
}

Zawsze porównuj HMAC obliczony na surowej treści (bez ponownej serializacji), w przeciwnym razie podpis się nie zgodzi.

7. Dziennik dostarczeń i ponowienia

Menu Webhooks Delivery Log wymienia każdą próbę wraz z jej statusem:

• SENT: dostarczone z kodem HTTP 2xx.
• PENDING: w kolejce, czeka na kolejny przebieg workera.
• FAILED: niepowodzenie tymczasowe, zaplanowano ponowienie.
• DEAD: niepowodzenie ostateczne po 6 próbach.

Ponowienia stosują wykładniczy backoff: 1 minuta, 5 minut, 30 minut, 2 godziny, a następnie 6 godzin. W każdej chwili możesz wymusić ponowną wysyłkę przyciskiem Replay oraz podejrzeć dokładny payload przez akcję Zobacz.

8. Multisklep, RODO i tryb batch

Każdy endpoint i każdy token są przypisane do konkretnego sklepu: przepływy jednego sklepu nigdy nie wyciekają do innego. Opcja Anonimizuj dane osobowe maskuje adresy e-mail, telefony i nazwiska przed wysyłką, aby zachować zgodność z RODO, gdy odbiorca nie powinien otrzymywać danych identyfikujących. Tryb batch grupuje wysyłki przy dużych wolumenach.

FAQ i rozwiązywanie problemów

Żaden webhook nie jest wysyłany. Sprawdź, czy worker cron jest zaplanowany i czy jego adres (z prawidłowym tokenem) odpowiada. Zajrzyj do dziennika: jeśli wpisy pozostają w statusie PENDING, cron nie działa.

Zdalny endpoint zwraca błąd 401 lub 403. Twoje narzędzie może oczekiwać weryfikacji podpisu: ustaw ten sam sekret po obu stronach albo usuń go na czas testów.

API przychodzące zwraca „insufficient_scope”. Użyty token nie ma zakresu wymaganego przez daną akcję. Zmodyfikuj token i zaznacz odpowiedni zakres (orders, products lub customers).

Strona testu pokazuje niepowodzenie. Przycisk Test wysyła przykładowy payload synchronicznie: niepowodzenie zwykle oznacza nieosiągalny adres URL albo nieprawidłowy certyfikat TLS po stronie odbiorcy.