# 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,…

- Strona: <https://www.datafirefly.com/pl/documentation/dfwebhooks/>
- Język: pl
- Zaktualizowano: 2026-07-31
- Inne języki: [fr](https://www.datafirefly.com/documentation/dfwebhooks/index.md), [en](https://www.datafirefly.com/en/documentation/dfwebhooks/index.md), [es](https://www.datafirefly.com/es/documentation/dfwebhooks/index.md), [de](https://www.datafirefly.com/de/documentation/dfwebhooks/index.md), [it](https://www.datafirefly.com/it/documentation/dfwebhooks/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfwebhooks/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfwebhooks/index.md)
- Indeks: <https://www.datafirefly.com/pl/documentation/llms.txt>

## 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.

Na start nie potrzebujesz żadnego płatnego abonamentu w Zapier, Make ani n8n: działa każda usługa zdolna odbierać lub wysyłać webhook HTTP.

## 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.

Token zawarty w adresie chroni dostęp do workera. Nie udostępniaj go i nie publikuj publicznie. Jeśli Twój hosting nie oferuje zadań cron, możesz skorzystać z usługi zewnętrznej (cron-job.org, EasyCron).

## 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).

Próg niskiego stanu magazynowego ustawia się w panelu _Ustawienia_ na ekranie głównym, podobnie jak czas retencji dzienników.

## 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`.

Podczas obsługi żądań przychodzących działa **ochrona anti-loop**: wywołane przez nie zmiany nigdy nie wyzwalają ponownie webhooka wychodzącego. Nie ma ryzyka nieskończonej pętli między sklepem a automatyzacjami.

## 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.