> ## Documentation Index
> Fetch the complete documentation index at: https://foliant-help.iforiti.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wysyłaj webhooki do własnego systemu

> Integracja Webhooki wysyła podpisane zdarzenie JSON na Twój własny endpoint, gdy Foliant wygeneruje dokument lub zakończy eksport.

Integracja **Webhooki** jest przeznaczona dla programistów. Wysyła zdarzenie JSON na wybrany przez Ciebie adres HTTPS za każdym razem, gdy coś się dzieje w Foliant. Dzięki temu Twój system może zareagować, na przykład archiwizując PDF każdej faktury albo pobierając gotowy eksport.

Webhooki są w wersji beta. Jeśli nie widzisz ich w **Ustawienia › Integracje**, nie są jeszcze dostępne dla Twojego sklepu. Skontaktuj się z pomocą techniczną, aby zapytać o dostęp.

## Zdarzenia

| Zdarzenie | Wysyłane, gdy |
| - | - |
| `document.generated` (**Wygenerowano dokument**) | Foliant tworzy dokument dla zamówienia: pobranie, eksport lub e-mail z PDF. |
| `export.completed` (**Eksport zakończony**) | Eksport zbiorczy jest gotowy. |

## Połącz webhooki

1. W Foliant przejdź do **Ustawienia › Integracje**.

2. Przy **Webhooki** kliknij **Połącz**.

3. Wypełnij ustawienia:

   | Pole | Co wpisać |
   | - | - |
   | **Adres URL endpointu** | Adres, na który Foliant wysyła zdarzenia. Musi używać HTTPS, np. `https://example.com/webhooks/foliant`. |
   | **Sekret podpisu** | Opcjonalnie. Z sekretem każde żądanie jest podpisane, więc możesz sprawdzić, czy pochodzi od Foliant. |
   | **Zdarzenia** | Zdarzenia do wysyłania. Domyślnie oba są zaznaczone. |

4. Kliknij **Połącz**.

Adres URL, sekret i zdarzenia możesz później zmienić w **Ustawienia** na stronie integracji.

## Co zawiera każde żądanie

Foliant wysyła żądanie `POST` z treścią JSON:

```json theme={null}
{
  "id": "a unique delivery id",
  "event": "document.generated",
  "created_at": "2026-10-11T09:30:00+00:00",
  "shop": "your-store.myshopify.com",
  "data": { }
}
```

### Dane `document.generated`

* `template`: `uuid` i `name` szablonu.
* `document_type`: `invoice`, `credit_note`, `quote` lub puste dla innych dokumentów.
* `order`: jego `id`, `name` i `type` (zamówienia lub wersje robocze zamówień).
* `refund_id` i `fulfillment_id`, gdy dokument dotyczy zwrotu pieniędzy lub przesyłki.
* `document_number` i `issued_at`, dla dokumentów numerowanych.
* `source`: sposób utworzenia, np. `download`, `admin_download`, `export` lub `email`.
* `export`: ID eksportu, gdy dokument jest częścią eksportu.
* `generated_at`.

### Dane `export.completed`

* `export`: jego `uuid`, `order_type`, `template_uuids`, liczba `orders`, `orders_skipped` (usunięte po wybraniu) i `documents`, `requested_by` (`merchant` lub `customer`) oraz `completed_at`.
* `download_url`: link do pobrania eksportu, oraz `download_url_expires_at`, czyli moment, w którym link przestaje działać.
* `download_expires_at`: kiedy wygasa sam eksport.

Zdarzenia zawierają identyfikatory i liczby, a nie adresy e-mail klientów.

### Nagłówki

| Nagłówek | Zawiera |
| - | - |
| `X-Foliant-Event` | Zdarzenie, np. `document.generated`. |
| `X-Foliant-Delivery` | Unikalne ID dostarczenia (takie samo jak `id` w treści). |
| `X-Foliant-Timestamp` | Czas wysłania w sekundach Unix. |
| `X-Foliant-Signature` | `sha256=`, a po nim podpis. Tylko gdy ustawisz sekret podpisu. |

## Sprawdź podpis

Podpis to szesnastkowy HMAC-SHA256 ze znacznika czasu, kropki i surowej treści żądania (`<timestamp>.<body>`), z Twoim sekretem podpisu jako kluczem. Oblicz go po swojej stronie i porównaj z wartością po `sha256=` w `X-Foliant-Signature`. Użyj surowej treści dokładnie w takiej postaci, w jakiej ją otrzymasz.

## Odpowiedzi i ponowienia

* Każda odpowiedź 2xx oznacza dostarczenie.
* Jeśli Twój endpoint zwróci błąd 5xx, 408 lub 429 albo nie odpowie w ciągu 10 sekund, Foliant spróbuje ponownie później, za każdym razem czekając dłużej, maksymalnie 5 razy.
* Inne odpowiedzi 4xx są ostateczne: Foliant ich nie ponawia.
* Każde zdarzenie jest dostarczane raz na dokument lub eksport. Po udanym dostarczeniu ponowienia nigdy nie wysyłają go drugi raz.

Każde dostarczenie widać w **Aktywność** na stronie integracji, gdzie możesz kliknąć **Ponów** przy nieudanym. Zobacz [Aktywność integracji](https://foliant-help.iforiti.com/pl/integrations/integration-activity.md).

## Powiązane artykuły

* [Połącz integrację i zarządzaj nią](https://foliant-help.iforiti.com/pl/integrations/connect-an-integration.md)
* [Aktywność integracji](https://foliant-help.iforiti.com/pl/integrations/integration-activity.md)
* [Automatyzuj za pomocą Shopify Flow](https://foliant-help.iforiti.com/pl/integrations/shopify-flow.md)
* [Eksportuj pliki PDF](https://foliant-help.iforiti.com/pl/exports/export-pdfs.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.