WEBHOOKS
Webhookok
Fogadjon valós idejű eseményeket a Superroute-tól — megrendelések, állapotváltozások, követési frissítések. Aláírt payload-okkal, automatikus újrapróbálkozással és beépített debuggerrel.
WEBHOOKS
Fogadjon valós idejű eseményeket a Superroute-tól — megrendelések, állapotváltozások, követési frissítések. Aláírt payload-okkal, automatikus újrapróbálkozással és beépített debuggerrel.
A webhook egy HTTP POST kérés, amelyet a Superroute az Ön által konfigurált URL-re küld, valahányszor történik valami — megrendelés készül, kézbesítés befejeződik, követési esemény rögzítésre kerül. Ön egy fogadó végpontot épít, mi oda kézbesítjük az eseményt.
Az események sorba kerülnek és aszinkron módon küldjük ki. Minden kérés HMAC-SHA256 aláírást hordoz az eredet ellenőrzésére. A sikertelen kézbesítéseket (nem 2xx vagy timeout) exponenciális backoff-fal legfeljebb 5-ször megismételjük.
Ön egy megosztott titkot konfigurál a beállítási oldalon. Minden kimenő webhookot ezzel írunk alá. A fogadó újraszámolja az aláírást és összehasonlítja — ha egyezik, a payload eredeti és sértetlen.
Nyolc kimenő eseménytípus érhető el. Mindegyiknek saját URL-mezője van a beállítási oldalon — bármilyen részhalmazra feliratkozhat.
Az összes kimenő esemény géppel olvasható leírása a tartalom sémáival, fejlécekkel és újrapróbálkozási ütemezésekkel (AsyncAPI 3.0): asyncapi-webhooks.json
Helyi kézbesítési megrendelés (Delivery / Pickup / P2P) létrehozásakor sül el bármilyen úton: web űrlap, REST/GraphQL API, e-commerce platform szinkron, automatikus szabályok, import sorok stb. A label-service és más nem-kézbesítési típusok ki vannak zárva. Batch folyamatban kihagyva, ha ugyanahhoz a címzetthez az order_create_async_postback_url is be van állítva. Állítsa be az order_create_webhook_url segítségével.
Payload PéldákMinden állapotátmenetnél elsül — felvéve, úton, kézbesítve, kivétel, törölve. Állítsa be a order_status_change_webhook_url segítségével.
Payload PéldákA csomag követési életciklusának minden eseményénél elsül. Állítsa be a tracking_event_webhook_url segítségével. A kézbesítési és felvételi események a kézbesítési igazolást is tartalmazzák: proof_files és proof_files_detail (file_id, type, url, full_url, aláírt letöltési URL). Az esemény után feltöltött fényképek pod.files_updated eseményként érkeznek. Minden fájl az eseményének kontextusát is tartalmazza: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) és service_status (1 = success / 2 = failed); rögzített esemény nélküli régi fájloknál null.
Payload PéldákEgyszer sül el egy kötegelt import feldolgozás befejezése után. A payload soronkénti eredménytömböt tartalmaz. Állítsa be a order_create_async_postback_url segítségével.
Payload PéldákAkkor sül el, ha egy kézbesítési fotót vagy aláírást hozzáadnak, lecserélnek vagy eltávolítanak (action: added / updated / removed) — fájlonként egy kézbesítés, nincs több melléklet-lekérdezés. A pod_files_webhook_url beállításával aktiválható. Minden fájl az eseményének kontextusát is tartalmazza: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) és service_status (1 = success / 2 = failed); rögzített esemény nélküli régi fájloknál null. Ha egy munkatárs lecserél egy fényképet vagy aláírást, vagy egy archivált verziót aktuálisként állít be, a fájl action: updated értékkel érkezik, és csak az aktuális képet tartalmazza; archivált verziók soha nem kerülnek elküldésre.
Payload PéldákAkkor sül el, ha egy rendelést véglegesen törölnek, így a rendszere követni tudja az eltávolítást. Az order_deleted_webhook_url beállításával aktiválható.
Payload PéldákAkkor sül el, ha egy lemondási kísérletet elutasítanak (például a rendelés már kiszállítás alatt áll), így az üzemeltetési folyamatai API-lekérdezés nélkül követhetik a sikertelen lemondásokat. Az order_cancel_failed_webhook_url beállításával aktiválható.
Payload PéldákAkkor aktiválódik, amikor egy útvonaltábla-hely gazdát cserél vagy a tábla állapota megváltozik — az action mező mondja meg, mi történt (claimed, standby, pooled, promoted, withdrawn, vetoed, replaced, assigned, awarded, lost, displaced, settled, board_opened, board_closed, board_cancelled). Csak vállalati szinten. Feliratkozás a route_board_webhook_url mezővel.
Payload PéldákKülön webhook-csatorna az okos csomagautomatákkal integrált külső kézbesítési szolgáltatóek számára. Az események a szolgáltatófiókjához beállított végpontra érkeznek, és minden végpont az eseménytípusok tetszőleges részhalmazára iratkozhat fel.
Ajtók Kinyitva — Abban a pillanatban aktiválódik, amikor a rekeszajtók kinyílnak egy kézbesítési kísérletnél — akár a futár a csomagautomata képernyőjén adta meg a hozzáférési kódot, akár a távoli nyitás API-t használta — beleértve az újrakiosztás miatti újranyitásokat is. Az opening blokk felsorol minden kinyitott rekeszt a grid_id-val, a hardveres ajtószámmal (compartment_number) és a pickup_locker_number-rel (megjelenítési sorszám, oszloponként fentről lefelé, majd balról jobbra számolva). Minden rekesz tartalmazza a pickup_locker_code mezőt is — a "{shelf_code}-{pickup_locker_number}" címkét, amelyhez a címzettet irányítjuk; null, ha a rekesznek nincs átvételi száma. A payload tartalmazza a pickup_code mezőt is — a címzett átvételi kódját, amelyet az ajtók kinyílásának pillanatában osztunk ki; a futár lerakási megerősítése után is ugyanaz a kód marad, átvételre azonban csak a lerakás megerősítése után használható.
Payload PéldákCsomagautomatába kézbesítve — Akkor sül el, ha a betárolás megerősítést kapott és a csomagok az automatában vannak. A tartalom a címzett átvételi kódját is tartalmazza. Minden rekesz tartalmazza a pickup_locker_code mezőt is — a "{shelf_code}-{pickup_locker_number}" címkét, amelyhez a címzettet irányítjuk; null, ha a rekesznek nincs átvételi száma. A távoli nyitás API-val nyitott ajtóknál a platform maga zárja le a betárolást, amint az automata minden nyitott ajtót zárva jelent, így az esemény confirm hívás nélkül is elsül; a confirmed_by a lezárás útját nevezi meg: courier_terminal, partner_api, door_close, timeout_door_closed vagy console.
Payload PéldákÁtvéve — Akkor sül el, ha a címzett átvette a betárolt csomagokat.
Payload PéldákSikertelen kézbesítés — Akkor sül el, ha egy kézbesítés meghiúsul; a csomagonkénti hibakódok is szerepelnek.
Payload PéldákLejárt — Akkor sül el, ha egy fel nem használt kézbesítési kód vagy át nem vett betárolás túllépi a lejárati idejét.
Payload PéldákTörölve — Akkor sül el, ha egy kézbesítést a befejezés előtt lemondanak.
Payload PéldákJavító újranyitás — Akkor sül el, ha a foglalt rekeszeket a javítási időablakon belül újranyitják egy téves elhelyezés kijavításához — az automata képernyőjéről vagy az API-n keresztül. A correction blokk felsorolja az újranyitott rekeszeket. Minden rekesz tartalmazza a pickup_locker_code mezőt is — a "{shelf_code}-{pickup_locker_number}" címkét, amelyhez a címzettet irányítjuk; null, ha a rekesznek nincs átvételi száma.
Payload PéldákÁtvételi kód megváltozott — Akkor aktiválódik, amikor a partner lecseréli egy kiszállítás kézbesítési vagy átvételi kódját. A rotation blokk megnevezi, melyik kódot cserélték le, mikor, és újraküldték-e a címzett értesítését — az új kód soha nem utazik webhookban; kizárólag a cserélő API közvetlen válaszában jelenik meg.
Payload PéldákSzállítói csomag elosztva — Akkor sül el, amikor egy raktárban átvett, előjelentett szállítói csomag a szállító által megnevezett helyszínre szóló elosztási rendelésre kerül. A data blokk a csomagszámot, a szállítói hivatkozást és a tagszámot, az elosztási rendelést (order_id, order_ref, status), valamint az indulási és célhelyszínt tartalmazza. Csak szolgáltatói fiókkal rendelkező szállítóknál kerül rögzítésre.
Payload PéldákSzállítói csomag felrakva — Akkor sül el, amikor a csomagot az indulási raktárban a teherautóra olvassák; a distribution.status in_transit, a loaded_at ki van töltve.
Payload PéldákSzállítói csomag kézbesítve a helyszínre — Akkor sül el, amikor a sofőr átadja az elosztási rendelést a helyszínen; a distribution.status delivered, a delivered_at ki van töltve. A betárolás későbbi, külön esemény.
Payload PéldákSzállítói csomag betárolva a helyszínen — Akkor sül el, amikor a csomagot a helyszínen betárolják, szekrényrekeszbe vagy polcra; a location tartalmazza a grid_id, grid_code és shelf_code értékeket. A címzett átvételi értesítése ekkor megy ki.
Payload PéldákSzállítói csomag eltávolítva az elosztásból — Akkor sül el, amikor a csomagot indulás előtt leveszik az elosztási rendelésről, vagy a rendelést törlik; a distribution.reason removed vagy cancelled. A csomag visszakerül a raktár elosztási listájára.
Payload PéldákAláírás és Ellenőrzés: A szolgáltató csomagautomata-webhookok saját aláírási sémát használnak: az X-Webhook-Signature értéke base64(HMAC-SHA256(titok, időbélyeg + "\n" + kézbesítési azonosító + "\n" + nyers törzs)), ahol az időbélyeg és a kézbesítési azonosító az X-Webhook-Timestamp és X-Webhook-Delivery-Id fejlécekből származik. Ellenőrizze az X-Webhook-Content-Digest fejlécet is (a törzs SHA-256 kivonata), és utasítsa el az elavult időbélyegeket. Az X-Webhook-Id az újrapróbálkozások között változatlan marad — használja idempotenciához.
Hogyan Konfigurálja: A végpontok a Külső kézbesítés → Szolgáltató csomagautomata → Beállítások alatt kezelhetők, szolgáltatóenként egy végpont, választható eseménylistával. A sikertelen kézbesítéseket exponenciális visszavárakozással legfeljebb 7-szer próbálja újra a rendszer, mielőtt holt levélbe kerülnének; a holt levélbe került események az események oldalról kézzel újraküldhetők.
Sandbox (tesztszekrény) események: A tesztszekrényekre létrehozott kézbesítések ugyanazokat a webhook eseményeket bocsátják ki, mint az éles környezet, ugyanazzal a titokkal aláírva, így valósághű forgalommal fejleszthet. A sandbox események háromféleképpen vannak megjelölve: a tartalom "livemode": false értéket hordoz, az event_id PLE-MOCK- előtaggal kezdődik, a kérés pedig tartalmazza az X-Webhook-Test: 1 fejlécet. Ha a végponton be van állítva sandbox URL, a sandbox események oda kerülnek a produkciós URL helyett; egyébként a produkciós URL-re esnek vissza, továbbra is megjelölve. A „Sandbox események kézbesítése" kapcsoló teljesen leállítja a sandbox kézbesítést.
A harmadik feles kézbesítési szolgáltatóknak (futároknak) küldött csomagkézbesítési webhookok. A kézbesítési megbízások életciklusát fedik le, így a futárnak többé nem kell lekérdezéssel figyelnie az új munkákat. Ez a kategória elkülönül az alábbi okos csomagautomata eseményektől: minden szolgáltató kategóriánként független végpontot, aláíró titkot és eseményfeliratkozást konfigurál — a saját portálján vagy a platform üzemeltetőjén keresztül.
Megbízás létrehozva — Akkor aktiválódik, amikor egy megrendelést a szolgáltatóhoz rendelnek — automatikus szabállyal vagy kézzel. A payload tartalmazza a megbízás számát, a megrendelés-azonosítókat és a csomagok követési számait.
Payload PéldákCsomagok átadva — Akkor aktiválódik, amikor a raktár a megbízás összes csomagját fizikailag átadta a szolgáltatónak.
Payload PéldákMegbízás törölve — Akkor aktiválódik, amikor a platform visszavon egy megbízást a szolgáltatótól. A reason mező megkülönbözteti: cancelled (a megbízást törölték a fuvarozónál), fallback_to_self_delivery (a platform visszavette a megrendelést saját kézbesítésbe) és reassigned (a megrendelést másik szolgáltatóhoz helyezték át).
Payload PéldákRészleges kézbesítés — Akkor indul, ha a küldemény egy részét kézbesítették, míg a többi csomag még úton van. A packages tömb csomagonként tartalmazza az eredményt, a legs pedig a fuvarozónál rögzített külső rendeléseket sorolja fel — csomagonként egyet, ha a fuvarozó nem fogad többdarabos küldeményt.
Payload PéldákAláírás és Ellenőrzés: A külső kézbesítési webhookok ugyanazt az aláírási sémát használják, mint a szolgáltató csomagautomata webhookok: az X-Webhook-Signature értéke base64(HMAC-SHA256(secret, timestamp + "\n" + delivery id + "\n" + raw body)), ahol a timestamp és a delivery id az X-Webhook-Timestamp és X-Webhook-Delivery-Id fejlécekből származik. Ellenőrizze az X-Webhook-Content-Digest fejlécet is (a törzs SHA-256 kivonata), és utasítsa el az elavult időbélyegeket. Az X-Webhook-Id az újrapróbálkozások során változatlan marad — használja idempotenciához.
Hogyan Konfigurálja: A szolgáltatók ezt a végpontot maguk konfigurálják a szolgáltatói portálon (Webhook beállítások), vagy a platform üzemeltetője teszi meg a Külső kézbesítés → Szolgáltatók → Webhooks alatt. Szolgáltatónként egy végpont, választható eseménylistával. Az aláíró titok automatikusan generálható vagy egyéni értékre állítható, és a beállítások oldalon megtekinthető. A sikertelen kézbesítéseket exponenciális visszavárakozással legfeljebb 7-szer próbálja újra a rendszer, mielőtt holt levélbe kerülnének; a holt levélbe került események kézzel újraküldhetők. A beállítások oldalról bármikor küldhető aláírt teszt (mock) esemény — a tesztkérések az X-Webhook-Test: 1 fejlécet viselik, és a payload adataiban "test": true szerepel.
Aláírt push-ok az Open Order Handoff Protocol-on cserélt átadásokról: életciklus-változások (elfogadva, elutasítva, lejárt, törölve), módosítási válaszok, követési események és új elszámolási sorok. OHP tokenenként a POST /api/v1/ohp/subscriptions útján feliratkozva; a végpontnak előbb vissza kell adnia egy challenge-et, mielőtt a feliratkozás létezne. Minden tartalom az OHP boríték; a message_id minden újrapróbálkozásnál azonos marad — ez alapján deduplikáljon. A pull marad az igazság forrása.
Aláírás és Ellenőrzés: X-Ohp-Signature: v1= + hex HMAC-SHA256 a "{timestamp}.{raw body}" felett a feliratkozás titkával. Az X-Ohp-Timestamp próbálkozásonként változik; az X-Ohp-Delivery egyenlő a message_id-vel. A CloudEvents és a Standard Webhooks feliratkozásonként érhető el.
Hogyan Konfigurálja: Az OHP tokennel kezelve: POST /api/v1/ohp/subscriptions (url, secret, events, format, signature), GET a listázáshoz, DELETE a visszavonáshoz. A géppel olvasható katalógus minden eseményt az ohp küldő alatt sorol fel.
Részletes, opcionálisan bekapcsolható események a klasszikus order.status_change webhook mellett (amely változatlan marad): ki lett hozzárendelve, elfogadta-e a sofőr, mikor vették fel a csomagot, mikor van úton, mikor kézbesítették vagy hiúsult meg, továbbá a sofőrök szolgálati változásai és a ritkított sofőrpozíciók. Semmi nem kerül elküldésre, amíg be nem állítja az alábbi URL-eket.
Sofőrt rendeltek a rendeléshez (kézzel, útvonaltervezéssel vagy automatikus hozzárendeléssel). data.source = auto_assign, ha az orkesztrátor végezte.
Payload PéldákA rendelés elvesztette a sofőrjét (átadás, visszavonás, elutasítás, időtúllépés). A data.previous_driver_id mutatja, kinél volt.
Payload PéldákA sofőr az alkalmazásban elfogadott egy automatikusan kiosztott rendelést (sofőrszolgálat kötelező elfogadással).
Payload PéldákA sofőr elutasított egy kiosztott rendelést; a data.reason tartalmazza az opcionális, szabad szöveges indokot.
Payload PéldákA sofőr megkezdte a felvételt (állapot: Felvétel megkezdve / Átvétel alatt).
Payload PéldákA csomagot felvették (állapot: Már felvéve).
Payload PéldákA csomag úton van a címzetthez (állapot: Kiszállítás megkezdve / Kézbesítés alatt).
Payload PéldákA kézbesítés sikerült (állapot: Sikeres).
Payload PéldákA kézbesítési kísérlet meghiúsult (Későbbi újrakézbesítés, Újraütemezés szükséges, Címzett elutasította).
Payload PéldákA rendelést törölték.
Payload PéldákEgy munkatárs (vagy engedélyezés esetén egy sofőr) készre jelölte a rendelést felvételre (Diszpécser beállítások → felvételre kész).
Payload PéldákEgy sofőr az alkalmazásban szolgálatba lépett vagy kilépett (sofőrszolgálat opció).
Payload PéldákSofőrpozíció az alkalmazásból vagy a nyomkövetőből, sofőrönként ritkítva a driver_location_min_interval_sec alapján (alapértelmezés 60 s). Csak a driver_location_webhook_url címre kerül elküldésre.
Payload PéldákHogyan Konfigurálja: Beállítások → Webhookok (vagy GET/PUT /api/v1/webhook-settings, GraphQL webhookSettingsUpdate): az order_lifecycle_webhook_url minden order.* eseményt és a driver.on_duty_changed eseményt kapja; az order_lifecycle_events ezt vesszővel elválasztott listára szűkíti; a driver_location_webhook_url és a driver_location_min_interval_sec vezérli a driver.location_update eseményt. Több URL vesszővel elválasztva adható meg. A kézbesítések a webhook kézbesítési naplóban jelennek meg reference_type order / driver értékkel.
Aláírás és Ellenőrzés: Pontosan úgy aláírva, mint fiókja minden más kimenő webhookja: örökölt Signature fejléc, valamint X-Webhook-Id / X-Webhook-Timestamp / X-Webhook-Signature-V2 az Ön webhook_sign_secret értékével. Az újrapróbálkozások ugyanazt az event_id értéket használják – ez alapján szűrje ki a duplikátumokat.
Opcionális események az okos csomagautomatái, kioszkjai és okos gyűjtődobozai által kezelt csomagokhoz: a csomag bekerült a gépbe, átvették, a személyzet kivette, vagy lejárt az átvételi határideje, valamint a hozzá nyitott vagy lezárt problémák. Kizárólag bővítés — egyetlen meglévő webhook sem változik, és semmi sem kerül kiküldésre, amíg be nem állítja a device_order_webhook_url értéket.
Egy csomag bekerült a gépbe, és a következő személyre vár (címzett, futár vagy üzemeltető, lásd data.device_order.next_actor). A due_at az átvételi határidő.
Payload PéldákA csomagot az vette ki, akire várt — a címzett, a futár vagy az okos gyűjtődobozt ürítő személyzet.
Payload PéldákA személyzet kivette a csomagot a gépből. A removal_reason adja meg az okát: overdue_return, handover, relay, anomaly vagy recovery.
Payload PéldákA csomag átvétel nélkül túllépte a due_at időpontot. Még a gépben van, és a kódja továbbra is működik; az overdue_at kitöltésre kerül, a next_actor pedig operator lesz.
Payload PéldákProbléma nyílt a kezeléshez (például door_left_open, deposit_unverified, item_missing, overdue). A data.exception tartalmazza az id, type, severity és status mezőket.
Payload PéldákValaki lezárt egy problémát a kezeléshez. A data.exception.status értéke resolved vagy dismissed, a resolution_action pedig megadja, mi történt.
Payload PéldákPayload Példák: data.device_order: id, kind, status, next_actor, device_type, device_id, device_name, grid_code, reference_number, order_id, external_order_id, due_at, overdue_at, stored_at, ended_at, removal_reason (az időpontok ISO 8601 formátumúak, null, amíg nem következnek be). A problémaesemények data.exception mezőt is tartalmaznak: id, type, severity, status, resolution_action. Az átvételi kód soha nem szerepel benne. Az event_id értéke DOE-<naplóesemény-azonosító>, és újrapróbálkozáskor sem változik.
Hogyan Konfigurálja: Beállítások → Webhookok (vagy GET/PUT /api/v1/webhook-settings): a device_order_webhook_url minden device_order.* eseményt megkap; a device_order_events ezt vesszővel elválasztott listára szűkíti. Több URL is megadható vesszővel elválasztva. A kézbesítések a webhook-kézbesítési naplóban jelennek meg reference_type device_order értékkel.
Aláírás és Ellenőrzés: Pontosan úgy aláírva, mint fiókja minden más kimenő webhookja: örökölt Signature fejléc, valamint X-Webhook-Id / X-Webhook-Timestamp / X-Webhook-Signature-V2 az Ön webhook_sign_secret értékével. Az újrapróbálkozások ugyanazt az event_id értéket használják – ez alapján szűrje ki a duplikátumokat.
Azokat a csomagokat, amelyeket egy partner fuvarozó a saját fiókjával szállít az Ön automatáiba, ez a csatorna nem küldi el; a partner a saját szolgáltatói csomagautomata-webhookjain keresztül kapja meg őket.
A webhookokat két szinten konfigurálhatja: vállalkozás szinten (mindenre kiterjed) vagy ügyfelenként (felülírja az adott B2B alfiókhoz).
Jelentkezzen be és lépjen a Beállítások → API és Webhookok menüpontba. Az ügyfél-felülírások az ügyfél részletek oldalán találhatók.
Válasszon legalább 16 karakter hosszú stringet, ideális esetben 32+ véletlen bájtot. A fogadó ezt használja az aláírás ellenőrzésére.
Csak azoknak az eseményeknek az URL-jét töltse ki, amelyek érdeklik. A többit hagyja üresen.
webhook_sign_secretÖn egy megosztott titkot konfigurál a beállítási oldalon. Minden kimenő webhookot ezzel írunk alá. A fogadó újraszámolja az aláírást és összehasonlítja — ha egyezik, a payload eredeti és sértetlen.order_create_webhook_urlHelyi kézbesítési megrendelés (Delivery / Pickup / P2P) létrehozásakor sül el bármilyen úton: web űrlap, REST/GraphQL API, e-commerce platform szinkron, automatikus szabályok, import sorok stb. A label-service és más nem-kézbesítési típusok ki vannak zárva. Batch folyamatban kihagyva, ha ugyanahhoz a címzetthez az order_create_async_postback_url is be van állítva. Állítsa be az order_create_webhook_url segítségével.order_status_change_webhook_urlMinden állapotátmenetnél elsül — felvéve, úton, kézbesítve, kivétel, törölve. Állítsa be a order_status_change_webhook_url segítségével.tracking_event_webhook_urlA csomag követési életciklusának minden eseményénél elsül. Állítsa be a tracking_event_webhook_url segítségével. A kézbesítési és felvételi események a kézbesítési igazolást is tartalmazzák: proof_files és proof_files_detail (file_id, type, url, full_url, aláírt letöltési URL). Az esemény után feltöltött fényképek pod.files_updated eseményként érkeznek. Minden fájl az eseményének kontextusát is tartalmazza: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) és service_status (1 = success / 2 = failed); rögzített esemény nélküli régi fájloknál null.order_create_async_postback_urlEgyszer sül el egy kötegelt import feldolgozás befejezése után. A payload soronkénti eredménytömböt tartalmaz. Állítsa be a order_create_async_postback_url segítségével.pod_files_webhook_urlAkkor sül el, ha egy kézbesítési fotót vagy aláírást hozzáadnak, lecserélnek vagy eltávolítanak (action: added / updated / removed) — fájlonként egy kézbesítés, nincs több melléklet-lekérdezés. A pod_files_webhook_url beállításával aktiválható. Minden fájl az eseményének kontextusát is tartalmazza: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) és service_status (1 = success / 2 = failed); rögzített esemény nélküli régi fájloknál null. Ha egy munkatárs lecserél egy fényképet vagy aláírást, vagy egy archivált verziót aktuálisként állít be, a fájl action: updated értékkel érkezik, és csak az aktuális képet tartalmazza; archivált verziók soha nem kerülnek elküldésre.order_deleted_webhook_urlAkkor sül el, ha egy rendelést véglegesen törölnek, így a rendszere követni tudja az eltávolítást. Az order_deleted_webhook_url beállításával aktiválható.order_cancel_failed_webhook_urlAkkor sül el, ha egy lemondási kísérletet elutasítanak (például a rendelés már kiszállítás alatt áll), így az üzemeltetési folyamatai API-lekérdezés nélkül követhetik a sikertelen lemondásokat. Az order_cancel_failed_webhook_url beállításával aktiválható.route_board_webhook_urlAkkor aktiválódik, amikor egy útvonaltábla-hely gazdát cserél vagy a tábla állapota megváltozik — az action mező mondja meg, mi történt (claimed, standby, pooled, promoted, withdrawn, vetoed, replaced, assigned, awarded, lost, displaced, settled, board_opened, board_closed, board_cancelled). Csak vállalati szinten. Feliratkozás a route_board_webhook_url mezővel.device_order_webhook_urlOpcionális események az okos csomagautomatái, kioszkjai és okos gyűjtődobozai által kezelt csomagokhoz: a csomag bekerült a gépbe, átvették, a személyzet kivette, vagy lejárt az átvételi határideje, valamint a hozzá nyitott vagy lezárt problémák. Kizárólag bővítés — egyetlen meglévő webhook sem változik, és semmi sem kerül kiküldésre, amíg be nem állítja a device_order_webhook_url értéket.Minden újdonság az API-ban és a webhookokban — idempotens lemondás, egyeztetési feedek, v2 aláírások, új események — másolható példákkal. Minden teljesen visszafelé kompatibilis.
Minden kimenő webhook hex-kódolt HMAC-SHA256 aláírást tartalmaz a fejlécben. A fogadónak újra ki kell számolnia az aláírást a nyers törzs felett a megosztott titokkal, és el kell utasítania a kérést, ha nem egyezik.
Minden webhook URL fogadhatja az eseményeket natív formátumban vagy CloudEvents formában, és kaphat Standard Webhooks aláírási fejléceket is. Ez URL-enként állítható a webhook beállításokban. A beállítás nélküli URL pontosan úgy kapja az eseményeket, mint eddig.
native — Az ezen az oldalon leírt JSON törzs és fejlécek.ce_binary — Ugyanaz a törzs; a CloudEvents attribútumok ce-* fejlécekben érkeznek.ce_structured — A törzs egy CloudEvent (Content-Type: application/cloudevents+json), a natív törzs a data mezőben van. Minden újrapróbálkozásnál azonos, és a natív aláírások ezt fedik le.A ce-id és a webhook-id az esemény saját event_id értékét tartalmazza, ha a törzsben van ilyen, különben az X-Webhook-Event-Id értékét. Maga az X-Webhook-Event-Id nem változik. A ce-source és a ce-srbusiness a vállalkozást jelöli, az ügyfeleinek küldött kézbesítéseknél is.
A partner csomagautomata-kézbesítések és a harmadik fél általi kézbesítés webhookjai végpontonként ugyanezt a választást kínálják, a szolgáltató webhook-beállítási oldalán. A rakodási terv és az Open Platform visszahívásai kérésenként kapják meg: callback_format és callback_signature, illetve callback.format és callback.signature. Ezeknél a ce-id és a webhook-id az esemény saját azonosítója (X-Webhook-Id, X-Webhook-Event-Id vagy X-Open-Delivery), a ce-source a küldő vállalkozást jelöli, és egy szolgáltatói kulcscsere után 24 óráig a webhook-signature kulcsonként egy aláírást tartalmaz.
Az adatkészlet-webhookok webhookonként ugyanezt a választást kínálják, a webhook űrlapján és az API-jában (event_format és standard_signature). A Standard Webhooks a webhook titkos kulcsát használja, ezért szükség van rá. Az adatkészlet-webhookok URL-jeinek nyilvános HTTPS-címeknek kell lenniük.
Standard Webhooks esetén minden kézbesítés tartalmazza a webhook-id, webhook-timestamp és webhook-signature fejlécet is. Minden újrapróbálkozásnál újra alá vannak írva, így az újrapróbálkozás is 5 perces tűrésen belül marad. A kulcs a webhook aláírókulcs whsec_ formában, amely a beállítások oldalon látható. A natív fejlécek továbbra is elküldésre kerülnek.
Minden küldő másképp ír alá. Az X-Webhook-Signature fejlécnevet három küldő három különböző eljárással használja; az Önt hívó küldő eljárásával ellenőrizzen.
| Küldő | Fejlécek | Aláírás |
|---|---|---|
| Bérlői webhookok (ez az oldal) | Content-Type, Signature, X-Webhook-Event-Id, X-Webhook-Timestamp, X-Webhook-Signature-V2 |
Signature = hex(HMAC-SHA256(body))
X-Webhook-Signature-V2 = hex(HMAC-SHA256(timestamp + "." + body)) |
| Partner csomagautomata-kézbesítések | Content-Type, X-Webhook-Id, X-Webhook-Delivery-Id, X-Webhook-Timestamp, X-Webhook-Key-Id, X-Webhook-Content-Digest, X-Webhook-Signature, X-Webhook-Test |
X-Webhook-Signature = "v1=" + base64(HMAC-SHA256(timestamp + "\n" + delivery_id + "\n" + body)) |
| Harmadik fél általi kézbesítés hozzárendelései | Content-Type, X-Webhook-Id, X-Webhook-Delivery-Id, X-Webhook-Timestamp, X-Webhook-Key-Id, X-Webhook-Content-Digest, X-Webhook-Signature |
X-Webhook-Signature = "v1=" + base64(HMAC-SHA256(timestamp + "\n" + delivery_id + "\n" + body)) |
| Rakodási terv visszahívások | Content-Type, X-Webhook-Event-Id, X-Webhook-Event-Type, X-Webhook-Timestamp, X-Webhook-Signature |
X-Webhook-Signature = "v1=" + hex(HMAC-SHA256(timestamp + "." + body)) |
| Open Platform feladat-visszahívások | Content-Type, X-Open-Event, X-Open-Delivery, X-Open-Job, X-Open-Timestamp, X-Open-Signature |
X-Open-Signature = "v1=" + hex(HMAC-SHA256(timestamp + "." + body)) |
| OHP push | Content-Type, X-Ohp-Event, X-Ohp-Delivery, X-Ohp-Timestamp, X-Ohp-Signature |
|
| Adatkészlet webhookok | Content-Type, X-Webhook-Event, X-Webhook-Timestamp, X-Webhook-Signature |
X-Webhook-Signature = hex(HMAC-SHA256(body)) |
| Bérlői webhookok Standard Webhooks beállítással | webhook-id, webhook-timestamp, webhook-signature |
webhook-signature = "v1," + base64(HMAC-SHA256(webhook-id + "." + webhook-timestamp + "." + body)) |
Szolgáltatója rendeléstípusonként (Helyi Kézbesítés, Címke szolgáltatás, Szállítási szolgáltatás, LTL szolgáltatás, Tárolási szolgáltatások, Költöztetési szolgáltatások, eszközrendelések) elrejtheti árait egy ügyfélfiók elől. Ha ez Önre vonatkozik, a végpontjára érkező kézbesítések nem tartalmaznak ármezőket: a shipping_price, price_details, currency, adó, pótdíjösszegek, díjszabási árak és hasonlók kimaradnak, nem nullaként érkeznek. A díjszabási listák megtartják a rate_id-t és a szolgáltatásneveket, hogy továbbra is választható legyen szolgáltatás.
A végpontnak gyorsan 2xx-szel kell válaszolnia. Egyébként, timeout vagy elérhetetlenség esetén a kézbesítés ismétlődik.
Másoljon be egy beérkezett payload-ot, a Signature fejléc értékét és a titkát — az eszköz a böngészőben újraszámolja az aláírást (semmi nem hagyja el ezt az oldalt), és jelzi, hogy egyezik-e.
Indítson egy valódi, megfelelően aláírt webhookot a szerverünkről egy Ön által megadott URL-re. Hasznos a fogadó elérhetőségének, a payload parsing-nak és az aláírás-ellenőrző logikának a teszteléséhez.
Tekintse meg a legutóbbi webhook kézbesítési kísérleteket a fiókján — valós produkciós eseményeket és erről az oldalról küldött teszteket. Bearer token beillesztése a betöltéshez.
A kézbesítési naplók 90 napig maradnak meg.
A kézi újrakézbesítés új X-Webhook-Event-Id értéket kap. Az esemény által hordozott event_id (pod.files_updated, order.deleted, életciklus- és eszközrendelési események) megtartja eredeti értékét.
| Idő | Esemény | URL | Státusz | HTTP | Próbálkozás | Idő (ms) | Teszt? | Műveletek |
|---|---|---|---|---|---|---|---|---|
| Még nincs webhook kézbesítés. | ||||||||