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 e-shopu. Webhooky se nastavují na úrovni celého účtu, 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 autentifikaci požadavku. Tuto hlavičku naleznete v nastavení jednotlivý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 obnovení tokenu pravděpodobně nebude váš server schopný přijímat webhooky po dobu, než nasadíte nový token.
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řijmout 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ěšné 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 e-mailem 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.
Opakované doručení (idempotence)
Webhooky doručujeme systémem „at-least-once": za určitých okolností (timeout, dočasná chyba nebo nedostupnost vašeho endpointu a následné opakované pokusy) může stejný webhook dorazit víckrát.
Každý webhook proto posíláme s hlavičkou X-Retino-Idempotency-Key. Pro danou událost je stabilní — při opakovaném doručení téhož webhooku je vždy stejná, u jiné události je jiná.
Doporučený postup na vaší straně:
Ukládejte si klíče už zpracovaných webhooků.
Když dorazí webhook s klíčem, který jste už zpracovali, akci neprovádějte znovu (vraťte 2xx, ale např. nevystavujte druhou poukázku).
Odpovězte 2xx jen po úspěšném zpracování; na 4xx/5xx (i timeout) webhook pošleme znovu.