Copy page

Zaslat API v2

Webhooky – změny stavu zásilek

Webhook je adresa URL ve vašem systému, na kterou Zaslat posílá HTTP požadavek pokaždé, když se změní stav některé z vašich zásilek. Nemusíte se tak na stav zásilek opakovaně dotazovat přes shipments/tracking; informace přijde sama krátce poté, co zpracujeme trackingová data dopravce.

Webhooky spravujete přes API v2 v sekci Webhooks API Reference. Všechny požadavky posíláte s hlavičkou x-apikey.

Registrace webhooku

Endpoint webhook/create zaregistruje adresu, na kterou chcete události dostávat:

Code
curl -X POST https://test.zaslat.cz/api/v2/public/webhook/create \
  -H "x-apikey: VAS_API_KLIC" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.example.com/webhooks/zaslat"}'

Odpověď obsahuje identifikátor webhooku a podpisový klíč v poli secret:

Code
{
  "id": 42,
  "url": "https://www.example.com/webhooks/zaslat",
  "event": "shipment.status_changed",
  "active": true,
  "createdAt": "2026-10-07T14:03:11+02:00",
  "failureCount": 0,
  "lastSuccessAt": null,
  "lastFailureAt": null,
  "disabledAt": null,
  "secret": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

Pravidla pro adresu:

• Pouze https://, bez přihlašovacích údajů v URL.
• Doménové jméno se musí přeložit na veřejnou IP adresu. Privátní, lokální a rezervované adresy (například 10.x, 192.168.x, 127.0.0.1, 169.254.x) jsou odmítnuty se stavem 400.
• Na jeden účet lze zaregistrovat nejvýše 10 webhooků. Stejnou adresu lze pro jednu událost zaregistrovat jen jednou; opakovaný pokus vrátí 409.

Správa webhooků

Pozastavený webhook ("active": false) si zachová nastavení, ale události na něj neposíláme a po obnovení je zpětně nedoručujeme.

Událost shipment.status_changed

Událost vzniká při změně souhrnného stavu zásilky v Zaslat (například INTRANSIT → ONDELIVERY → DELIVERED), nikoli při každém záznamu trackingu dopravce. Slovník stavů vychází ze sledování zásilek (CREATED, EXPORTED, ONPICKUP, INTRANSIT, ONDELIVERY, DELIVERED, CANCELLED; význam popisuje stránka Sledování zásilek a stavy) a navíc rozlišuje dva stavy:

• PARCELSHOP – zásilka je uložena na výdejním místě nebo v boxu a čeká na vyzvednutí příjemcem.
• DONE_AUTO – zásilku jsme uzavřeli automaticky, protože dopravce 90 dní neposlal žádný nový stav.

Na vaši adresu přijde požadavek POST s tělem application/json:

Code
{
  "event": "shipment.status_changed",
  "eventId": "7f2a0b9c-4d3e-4f61-9a8b-2c1d0e5f6a7b",
  "version": 1,
  "occurredAt": "2026-10-07T14:03:11+02:00",
  "test": false,
  "data": {
    "id": 4815162,
    "trackingNumber": "IZ3F9A2C71B4",
    "carrierNumber": "13606100012345",
    "referenceNumber": "ORDER-2026-1042",
    "carrier": { "code": "dpd", "name": "DPD" },
    "status": "DELIVERED",
    "trackingUrl": "https://www.zaslat.cz/cs/sledovani-zasilek/IZ3F9A2C71B4",
    "lastTrackingEvent": {
      "date": "2026-10-07 13:58:00",
      "status": "DELIVERED",
      "name": "Zásilka byla doručena příjemci",
      "location": "Praha 5"
    }
  }
}

Událost obsahuje pouze identifikátory a nový stav. Podrobnosti o zásilce včetně adres si v případě potřeby načtěte přes API.

Ověření podpisu

Každý požadavek nese hlavičku X-Zaslat-Signature ve tvaru sha256=<hex>, kde <hex> je HMAC-SHA256 nezměněného těla požadavku vypočtený podpisovým klíčem webhooku. Na své straně podpis spočítejte z přesně přijatých bajtů těla a porovnejte jej s hlavičkou porovnáním v konstantním čase. Požadavek s neplatným podpisem odmítněte.

Hlavičky X-Zaslat-Event a X-Zaslat-Event-Id opakují hodnoty event a eventId z těla a hodí se pro směrování požadavku ještě před jeho zpracováním. API klíč se na webhook nikdy neposílá.

Code
$body = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, $secret);

if (!hash_equals($expected, $_SERVER['HTTP_X_ZASLAT_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}

Code
const crypto = require("crypto");

const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const received = req.headers["x-zaslat-signature"] ?? "";

if (received.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))) {
  res.status(401).end();
  return;
}

Doručování a opakování

Váš endpoint musí odpovědět stavem 2xx do 10 sekund. Přesměrování nenásledujeme a počítá se jako selhání.

Pokud všechny pokusy o doručení selhávají nepřetržitě 24 hodin, webhook automaticky pozastavíme: pole active se změní na false, čas pozastavení najdete v poli disabledAt a na notifikační e-mail účtu odešleme upozornění. Události vzniklé během pozastavení se neposílají ani zpětně nedoručují. Po opravě endpointu webhook obnovíte požadavkem PATCH webhook/update/{id} s tělem {"active": true}; tím se vynuluje i čítač failureCount.

Stav doručování sledujte v polích failureCount, lastSuccessAt a lastFailureAt detailu webhooku a v endpointu webhook/deliveries/{id}, který vrací posledních 50 pokusů včetně stavového kódu a popisu chyby. Záznamy starší než 30 dní se mažou.

Testovací událost

Endpoint POST webhook/test/{id} ihned odešle na adresu webhooku jednu událost shipment.status_changed se smyšlenými daty zásilky a "test": true, podepsanou stejně jako skutečná událost, a vrátí, jak váš endpoint odpověděl:

Code
curl -X POST https://test.zaslat.cz/api/v2/public/webhook/test/42 \
  -H "x-apikey: VAS_API_KLIC"

Code
{
  "eventId": "c1a2b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "delivered": true,
  "statusCode": 200,
  "error": null
}

Testovací událost se odešle i na pozastavený webhook a nikdy neovlivní čítače selhání ani automatické pozastavení; v přehledu doručení je označena "test": true. Neúspěšný test vrátí také stav 200, výsledek poznáte z polí delivered, statusCode a error. Endpoint je omezen na 10 požadavků za 60 sekund na účet; po překročení limitu dostanete 429.