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

# Szybki start z webhookami

> Otrzymuj na swoim serwerze zdarzenia z Zippendo w czasie rzeczywistym, gdy zmieniają się przesyłki, zamówienia i śledzenie.

Webhooki informują Twoje systemy w chwili, gdy coś dzieje się w Zippendo, na przykład gdy przesyłka zostaje wysłana albo zmienia się status śledzenia. Dzięki temu Twój sklep internetowy lub system ERP jest na bieżąco, bez ciągłego odpytywania API.

<Note>
  Webhooki są wliczone w każdy plan.
</Note>

## 1. Dodaj webhook

<Steps>
  <Step title="Otwórz Webhooki">
    W [app.zippendo.com](https://app.zippendo.com) otwórz menu organizacji na dole paska bocznego, kliknij **Zarządzaj**, a potem **Webhooki**.
  </Step>

  <Step title="Utwórz webhook">
    Kliknij **Dodaj webhook**. Wpisz **Nazwa** i **Docelowy adres URL**, zaznacz **Zdarzenia**, które chcesz otrzymywać, i kliknij **Utwórz webhook**.
  </Step>

  <Step title="Pobierz klucz podpisu">
    Zippendo tworzy klucz podpisu dla każdego webhooka. Aplikacja go nie pokazuje: odczytasz go przez API z `GET /orgs/{orgId}/webhooks/{webhookId}` albo z odpowiedzi, gdy tworzysz webhook przez API za pomocą `POST /orgs/{orgId}/webhooks`. Przechowuj go na swoim serwerze i weryfikuj podpis przy każdym dostarczeniu.
  </Step>
</Steps>

## 2. Zdarzenia

| Zdarzenie | Wysyłane, gdy |
| - | - |
| `shipment.created` | Przesyłka zostaje utworzona |
| `shipment.updated` | Przesyłka zostaje zmieniona |
| `shipment.dispatched` | Przesyłka zostaje wysłana do przewoźnika |
| `shipment.cancelled` | Przesyłka zostaje usunięta |
| `shipment.error` | Wysłanie przesyłki do przewoźnika się nie udaje |
| `order.created` | Zamówienie zostaje utworzone w aplikacji lub przez API |
| `order.updated` | Zamówienie zostaje zmienione w aplikacji lub przez API |
| `order.cancelled` | Zamówienie zostaje usunięte w aplikacji lub przez API |
| `tracking.updated` | Paczka dostaje nowe zdarzenie śledzenia |

Zamówienia zaimportowane z kanału sprzedaży nie wysyłają zdarzeń `order.*`. **Wyślij test** przy webhooku wysyła zdarzenie `webhook.test` na ten jeden adres.

## 3. Zasady dostarczania

Każde dostarczenie to żądanie HTTPS `POST` z treścią JSON w postaci `{ "event", "timestamp", "brandId", "data" }` i trzema nagłówkami:

| Nagłówek | Wartość |
| - | - |
| `X-Webhook-Signature` | HMAC-SHA256 **surowej treści żądania**, zapisany szesnastkowo, z kluczem podpisu webhooka |
| `X-Webhook-Event` | Nazwa zdarzenia, na przykład `shipment.dispatched` |
| `X-Webhook-Id` | Unikalny identyfikator dostarczenia. Ponowione dostarczenie zachowuje ten sam identyfikator. |

Dostarczenie wygasa po **10 sekundach**. Każda odpowiedź inna niż 2xx lub przekroczenie czasu liczy się jako niepowodzenie, a Zippendo próbuje ponownie z rosnącą przerwą: łącznie **do 5 prób**. Każda próba, udana lub nie, jest widoczna w **Dziennik dostarczeń** webhooka w sekcji **Webhooki**.

## 4. Obsługa dostarczeń

Twój adres docelowy powinien:

* Szybko odpowiadać statusem **2xx**, a ciężką pracę wykonywać w tle
* Używać **HTTPS**
* Weryfikować podpis, zanim zaufa treści
* Bezpiecznie obsługiwać ponowienia: użyj `X-Webhook-Id`, aby pominąć dostarczenie, które już przetworzono

```javascript theme={null}
import crypto from "node:crypto"

export async function POST(request) {
  const body = await request.text()

  const expected = crypto.createHmac("sha256", process.env.ZIPPENDO_WEBHOOK_SECRET)
    .update(body)
    .digest("hex")
  const signature = request.headers.get("x-webhook-signature") ?? ""
  const valid = signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  if (!valid) return new Response("invalid signature", { status: 401 })

  queueMicrotask(() => processZippendoEvent(JSON.parse(body)))
  return new Response("ok", { status: 200 })
}
```

## 5. Testuj w trakcie tworzenia

Użyj tunelu (na przykład ngrok), aby nadać serwerowi deweloperskiemu publiczny adres HTTPS, taki jak `https://your-tunnel.ngrok.io/webhooks/zippendo`. Skieruj na niego testowy webhook i kliknij **Wyślij test**.

## Następne kroki

<CardGroup cols={2}>
  <Card title="Przewodnik po webhookach" icon="book-open" href="/docs/pl/settings/webhooks">
    Edytuj, wstrzymuj i usuwaj webhooki oraz czytaj dziennik dostarczeń.
  </Card>

  <Card title="REST API" icon="terminal" href="/docs/pl/quickstarts/rest-api">
    Łącz webhooki z wywołaniami API, gdy potrzebujesz danych na żądanie.
  </Card>
</CardGroup>


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