Webhooky

Webhooky jsou způsob jak získávat upozornění z Retina o různých událostech. Místo periodického stahování informací přes API si můžete vytvořit webhook a my vám na určenou adresu budeme posílat upozornění o změnách v Retinu v reálném čase.

Nastavení webhooků naleznete v Nastavení > Webhooky, odsud si můžete vytvořit webhook a monitorovat již existující.

Tvorba webhooku

Přidejte si na vašem serveru novou url adresu, kterou použijete pro přijímání webhooků, např. vas-eshop.cz/webhook-retino, což bude adresa, na kterou vám budeme posílat metodou POST ve formátu JSON upozornění na vybrané události.

Poté přejděte do Nastavení > Webhooky a klikněte na Přidat endpoint. Webhooky jsou integrovány do Automatizace Trackingu, takže zde vytvořte novou automatizaci, vyberte požadovanou spouštěcí událost, o které chcete být informováni, a jako akci zvolte Webhook a vložte nově vytvořenou url adresu z vašeho eshopu. Webhooky se nastavují na úrovni celého účtu a takže nejsou omezeny na jednotlivé uživatele.

Jakmile budete mít nový webhook vytvořený, můžete zkusit odeslat testovací událost, kterou najdete v detailu tohoto nově vytvořeného webhooku. Po odeslání testovací události se vám zobrazí data odeslaná na váš server, stavový kód odpovědi vašeho serveru a data odeslaná vaším serverem jako odpověď. Tyto údaje jsou velmi užitečné při hledání chyb v integraci.

Zabezpečení

Všechny události odeslané naším serverem na URL adresu vašeho webhooku obsahují hlavičku X-Retino-Secret ve tvaru:

X-Retino-Secret: <token>

Ta slouží k authentizaci požadavku. Tuto hlavičku naleznete v nastavení jednolivých webhooků.

Obnovení tajného tokenu

Pokud máte podezření, že váš token byl kompromitován, můžete v nastavení webhooku takový token obnovit. POZOR, po obnovaní tokenu nebude váš server schopný pravděpodobně po dobu, než nasadíte nový token, přijímat webhooky.

Používejte HTTPS

Důrazně doporučujeme, aby komunikace probíhala přes šifrovaný protokol HTTPS. Pokud váš webhook bude pod protokolem HTTP, budeme vás na to upozorňovat v nastavení webhooků.

Typy událostí

Webhook může být navázán na několik typů událostí zároveň. Každá z událostí odesílá informace o případu, produktech, dopravě a přidružené objednávce.

Doprava vytvořena
Stav dopravy se změnil
Stav dopravy se nezměnil po dobu N dnů
Zásilka čeká na pobočce po dobu N dnů
Zbývá N dnů z doby uložení na pobočce

Formát dat

Webhook odesílá data ve formátu JSON. Formát dat je totožný s modelem Shipping z Tracking API. Při každé události se odešle celá instance dopravy obsahující historii stavů, výjimky a přiřazené štítky.

{
  "carrier": "TOPTRANS",
  "carrier_estimated_delivery": null,
  "delivered_at": "2024-11-05T12:09:00+01:00",
  "delivery_type": "TO_ADDRESS",
  "destination_country": "CZ",
  "id": "3104447e-d019-453c-96ec-2805daf937b4",
  "issues": [
    {
      "created_at": "2024-11-05T04:30:00+01:00",
      "is_resolved": false,
      "note": "",
      "shipping_id": "3104447e-d019-453c-96ec-2805daf937b4",
      "status": "EXCEPTION",
      "sub_status": "EXCEPTION",
      "type": null
    }
  ],
  "last_sync_at": "2024-12-18T14:30:45.300195+01:00",
  "order_code": "ORDER-CODE",
  "ordered_at": "2024-10-31T15:02:00+01:00",
  "original_tracking_number": "TEST-TRACKING-NUMBER",
  "picked_from_branch_at": null,
  "pickup_at": "2024-11-04T09:57:00+01:00",
  "source": null,
  "status": "DELIVERED",
  "stored_until": null,
  "sub_status": "DELIVERED",
  "tags": [
    "049a18e5-5378-42b2-bfc0-19bcee2a02d7"
  ],
  "tracking": [
    {
      "carrier_description": "Zásilka doručena",
      "created_at": "2024-11-05T12:09:00+01:00",
      "location": "001 - Praha",
      "status": "DELIVERED",
      "sub_status": "DELIVERED"
    },
    {
      "carrier_description": "Zásilka se rozváží",
      "created_at": "2024-11-05T09:18:00+01:00",
      "location": "001 - Praha",
      "status": "OUT_FOR_DELIVERY",
      "sub_status": "OUT_FOR_DELIVERY"
    },
    {
      "carrier_description": "Chybné nasortování na depo",
      "created_at": "2024-11-05T04:30:00+01:00",
      "location": "001 - Praha",
      "status": "EXCEPTION",
      "sub_status": "EXCEPTION"
    },
    {
      "carrier_description": "Zásilka je na rozvozovém středisku",
      "created_at": "2024-11-05T01:40:00+01:00",
      "location": "001 - Praha",
      "status": "IN_TRANSIT",
      "sub_status": "IN_TRANSIT__DEPOT"
    },
    {
      "carrier_description": "Zásilka odešla do cílového střediska",
      "created_at": "2024-11-04T16:22:00+01:00",
      "location": "-",
      "status": "IN_TRANSIT",
      "sub_status": "IN_TRANSIT"
    },
    {
      "carrier_description": "Zásilka svezena do skladu",
      "created_at": "2024-11-04T09:57:00+01:00",
      "location": "750 - Ostrava",
      "status": "IN_TRANSIT",
      "sub_status": "IN_TRANSIT__HUB"
    },
    {
      "carrier_description": "Přijata objednávka přepravy",
      "created_at": "2024-11-04T06:41:00+01:00",
      "location": "750 - Ostrava",
      "status": "INFORMATION_RECEIVED",
      "sub_status": "INFORMATION_RECEIVED"
    }
  ],
  "tracking_number": "TEST-TRACKING-NUMBER",
  "tracking_url": "https://apis.toptrans.cz/tracking?parcel_number=TEST-TRACKING-NUMBER"
}

O doručování webhooků

Retino odesílá webhooky http metodou POST ve formátu JSON. Váš server musí být připraven příjmout tato data a odpovědět na ně v časovém limitu 10 sekund odpovědí se stavovým kódem <= 2xx (200, 201, …) (stavové kódy přesměrování 3xx nejsou akceptovány, protože jde o metodu POST).

Úspěsné doručení

Webhook bude úspěšně doručen, pokud:

váš server odpoví v časovém limitu 10 sekund
odpověď bude mít úspěšný stavový kód (2xx)

Opakování doručení

Pokud váš server neodpoví do 10 sekund, nebo odpoví chybovým stavovým kódem, doručení webhooku selže. Náš server se bude snažit doručit takový webhook v intervalu 72 hodin s exponenciální prodlevou.

Pokud doručení jednoho webhooku nebude úspěšné ani po 72 hodinách od vytvoření, budeme vás informovat emailem a zašleme vám všechny relevantní informace.

Pokud během 72 hodin selžou všechny webhooky mířící na jeden endpoint, pak takový endpoint deaktivujeme a budeme vás o této události informovat emailem.